APM 배포 추적을 DORA Metrics의 배포를 위한 데이터 소스로 구성할 수 있습니다.

요구 사항

• APM Deployment Tracking이 DORA 설정에서 Deployments 이벤트 데이터 소스로 활성화되어 있어야 합니다.
• 서비스가 Software Catalog에 메타데이터와 함께 정의되어 있어야 합니다.
• 서비스에 unified service tagging이 활성화되어 있어야 합니다. 배포는 version 태그를 사용하여 식별됩니다.

APM에 의해 추적된 서비스 배포가 변경 리드 타임에 기여하도록 보장하는 방법에 대한 자세한 내용은 커밋 정보로 배포 보강을 참조하세요.

자체 배포 이벤트를 전송하려면 DORA Metrics API 또는 datadog-ci dora deployment 명령을 사용하세요.

요구 사항

• DORA 설정에서 datadog-ci CLI / API이 Deployments 이벤트 데이터 소스로 활성화되어 있어야 합니다.
• 필수 속성은 다음과 같습니다.
  • started_at: 배포가 시작된 시간입니다.
  • finished_at: 배포가 완료된 시간입니다.
  • service: 배포된 서비스입니다. 제공된 서비스가 Software Catalog에 등록되어 있고 메타데이터가 설정되어 있는 경우(메타데이터 추가 참조), 서비스의 team이 자동으로 조회되어 모든 메트릭과 연결됩니다.

배포 이벤트에 다음 속성을 선택적으로 추가할 수 있습니다.

• repository_url: 서비스의 소스 코드 저장소입니다. 변경 리드 타임을 계산하는 데 필요합니다.
• commit_sha: 배포와 관련된 HEAD 커밋의 SHA입니다. 변경 리드 타임을 계산하는 데 필요합니다.
• team: 서비스에 대해 자동으로 검색된 것과 다른 team에 배포를 연결합니다.
• env: DORA Metrics 페이지에서 환경별로 DORA 메트릭을 필터링합니다.
• id: 배포를 식별합니다. 이 속성은 사용자가 생성한 속성입니다. 지정하지 않으면 엔드포인트는 Datadog가 생성한 UUID를 반환합니다.
• version: 배포 버전입니다.
• custom_tags: DORA Metrics 페이지에서 이벤트를 필터링하는 데 사용할 수 있는 key:value 형식의 태그입니다.

API(cURL) 예제

전체 사양 및 추가 코드 샘플은 DORA Metrics API 참조 설명서를 참조하세요.

다음 예제에서는 URL의 <DD_SITE>를 으로 바꾸고 ${DD_API_KEY}를 Datadog API 키로 바꿉니다.

  curl -X POST "https://api.<DD_SITE>/api/v2/dora/deployment" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "DD-API-KEY: ${DD_API_KEY}" \
  -d @- << EOF
  {
    "data": {
      "attributes": {
        "service": "shopist",
        "started_at": 1693491974000000000,
        "finished_at": 1693491984000000000,
        "git": {
          "commit_sha": "66adc9350f2cc9b250b69abddab733dd55e1a588",
          "repository_url": "https://github.com/organization/example-repository"
        },
        "env": "prod",
        "team": "backend",
        "version": "v1.12.07",
        "custom_tags": ["department:engineering", "app_type:backend"]
      }
    }
  }
EOF

CLI 예제

datadog-ci CLI 도구를 사용하면 Continuous Integration 환경에서 손쉽게 배포 이벤트를 전송할 수 있습니다.

다음 예제에서는 DD_SITE 환경 변수를 으로 설정하고 DD_API_KEY 환경 변수를 Datadog API 키로 설정합니다.

export DD_SITE="<DD_SITE>"
export DD_API_KEY="<DD_API_KEY>"

export deploy_start=`date +%s`
./your-deploy-script.sh
datadog-ci dora deployment --service shopist --env prod \
    --started-at $deploy_start --finished-at `date +%s` \
    --version v1.12.07 --custom-tags department:engineering \
    --custom-tags app_type:backend \
    --git-repository-url "https://github.com/organization/example-repository" \
    --git-commit-sha 66adc9350f2cc9b250b69abddab733dd55e1a588

--finished-at을 지정하지 않으면 배포 종료 시간은 현재 시각으로 자동 설정됩니다.

배포 CI 작업이 실제 배포되는 Git 리비전과 동일한 경우 git-repository-url 및 git-commit-sha은 생략할 수 있으며 CI 컨텍스트에서 자동으로 추론됩니다.

--skip-git 옵션을 사용하면 저장소 URL과 커밋 SHA 전송을 비활성화할 수 있습니다. 이 옵션을 추가하면 변경 리드 타임 메트릭을 사용할 수 없게 됩니다.

APM 배포 추적으로 식별되는 배포의 경우 애플리케이션 텔레메트리에 Git 정보 태그가 포함되어 있어야 합니다.

• APM에서에서 Git 태깅을 활성화하거나 소스 코드 통합 설명서를 참조하세요.

참고: APM으로 추적되는 배포의 경우 변경 리드 타임은 커밋 생성 시점부터 해당 커밋이 새 버전에서 처음 관찰되는 시점까지를 기준으로 계산됩니다. Deploy Time 메트릭은 사용할 수 없습니다.

DORA Metrics API 또는 datadog-ci dora deployment 명령으로 추적되는 배포의 경우 다음을 확인하세요.

• 배포 이벤트 페이로드에 repository_url 및 commit_sha 속성이 포함되어 있어야 합니다.

GitHub 통합이 이미 설치되어 있지 않은 경우, GitHub 통합 타일에서 설치하세요.

GitHub 애플리케이션을 구성할 때:

1. 최소한 Read 리포지토리 권한에 대해 Contents 및 Pull Requests 권한을 선택하세요.
2. 최소한 Push, PullRequest 및 PullRequestReview 이벤트를 구독하세요.

설정이 유효한지 확인하려면 GitHub 통합 타일에서 GitHub 애플리케이션을 선택하고 Datadog Features 표에 Pull Request Information이 모든 요구 사항을 충족하는 것으로 표시되는지 확인하세요.

GitLab 소스 코드 통합이 아직 설치되지 않은 경우 GitLab 소스 코드 통합 타일에 설치합니다.

참고: 서비스 계정의 개인 액세스 토큰 범위는 최소 read_api 이상이어야 합니다.

GitLab 그룹 및 하위 그룹 처리

리포지토리가 GitLab 그룹 또는 하위 그룹(예: https://gitlab.com/my-org/group(/subgroup)/repo) 아래에 구성된 경우, GitLab의 중첩 그룹 구조로 인해 자동 서비스 경로 감지가 올바르게 동작하지 않을 수 있습니다.

DORA 메트릭이 서비스의 소스 코드 경로를 올바르게 처리할 수 있도록 서비스 정의에서 다음 구성을 사용할 수 있습니다.

extensions:
  datadoghq.com/dora-metrics:
    source_patterns:
      # All paths relative to the repository URL provided with the deployment
      - **
      # or specific paths related to this service (for monorepos)
      - src/apps/shopist/**
      - src/libs/utils/**

Azure DevOps 소스 코드 통합이 아직 설치되지 않은 경우 Azure DevOps 소스 코드 통합 타일에 설치합니다.

통합 설정 방법:

1. Datadog에서 Azure DevOps 소스 코드 통합 타일을 엽니다.

2. Configuration 탭을 선택하고 Connect Microsoft Entra App을 클릭합니다.

3. 설정 지침을 따릅니다.

4. Add Organizations를 클릭합니다.

5. 리포지토리 설치 단계를 따르고 설정 스크립트를 실행합니다. 스크립트를 실행하지 않으면 풀 요청이 생성되기 이전에 이루어진 커밋이 해당 풀 요청과 연결되지 않습니다.

6. 스크립트가 완료되면 타일에서 통합 상태를 확인합니다. 연결된 리포지토리와 프로젝트가 목록에 표시됩니다.

datadog-ci git-metadata upload 명령을 사용하여 Git 리포지토리 메타데이터를 업로드할 수 있습니다. 이 명령이 실행되면 Datadog은 리포지토리 URL, 현재 브랜치의 커밋 SHA, 추적된 파일 경로 목록을 수신합니다.

새 커밋마다 CI에서 이 명령을 실행하세요. 특정 커밋 SHA에 대해 배포가 실행되는 경우, 배포 이벤트가 전송되기 전에 해당 커밋에 대해 datadog-ci git-metadata upload 명령을 실행해야 합니다.

명령 출력에서 명령의 설정이 올바른지 확인할 수 있습니다. 올바른 출력 예시는 다음과 같습니다.

Reporting commit 007f7f466e035b052415134600ea899693e7bb34 from repository git@github.com:organization/example-repository.git.
180 tracked file paths will be reported.
✅  Handled in 0.077 seconds.

DORA Metrics는 Datadog 인시던트를 통해 실패를 자동으로 식별하고 추적할 수 있습니다. 인시던트가 선언되면 DORA는 이를 사용하여 변경 실패율과 복구 시간을 측정합니다.

참고: 복구 시간은 인시던트가 active 상태에 머문 전체 시간으로 측정됩니다. active → stable → active → stable와 같은 상태 전이가 발생한 경우, 모든 active 상태 기간이 포함됩니다. 복구 시간은 인시던트가 stable 또는 resolved 상태일 때만 표시됩니다. resolved 상태의 인시던트가 다시 활성화되면 해당 메트릭은 숨겨지며, 다시 resolved 상태가 되면 표시됩니다.

요구 사항

• Incidents가 DORA 설정에서 Failures 이벤트 데이터 소스로 활성화되어 있어야 합니다.

레이블 없는 실패를 방지하기 위해 Datadog은 다음 속성을 인시던트에 추가할 것을 강력히 권장합니다.

• Teams
• Services
• Envs: Envs 속성이 없는 경우 인시던트 설정에서 추가할 수 있습니다.

이 속성이 인시던트에 제공되면 실패 이벤트에 Severity 태그가 추가됩니다.

권장: 인시던트 설정에서 속성 필드 Prompted를 At Resolution으로 설정하면 인시던트 생성 시 해당 속성을 누락하는 일을 방지할 수 있습니다.

과거 인시던트 포함

DORA 설정에서 Backfill Data를 선택하면 지난 2년간의 인시던트를 소급 적용하여 실패 이벤트를 생성할 수 있습니다. 데이터 보충은 완료까지 최대 1시간이 소요될 수 있습니다.

PagerDuty는 IT 팀이 인시던트를 즉시 파악하고 대응할 수 있도록 지원하는 인시던트 관리 플랫폼으로, 운영 안정성과 복원력을 유지하는 데 도움을 줍니다.

PagerDuty 계정을 DORA Metrics와 통합하려면 다음을 수행하세요.

1. DORA 설정에서 PagerDuty를 Failures 이벤트 데이터 소스로 활성화합니다.

2. PagerDuty에서 Integrations > Developer Tools으로 이동한 후 Generic Webhooks (v3)를 클릭합니다.

3. + New Webhook을 클릭하고 다음 세부 정보를 입력합니다.

   변수	설명
   웹훅 URL	추가 https://webhook-intake./api/v2/webhook/.
   범위 유형	전송할 인시던트의 범위를 선택합니다. 특정 Service 또는 Team에 대해 또는 Account 내의 모든 PagerDuty 서비스에 대해 인시던트를 전송할 수 있습니다. 환경 및 권한 수준에 따라 일부 범위 유형은 사용할 수 없을 수 있습니다.
   설명	설명은 웹훅을 구분하는 데 도움이 됩니다. 예를 들어 다음과 같은 설명을 추가할 수 있습니다. Datadog DORA Metrics integration.
   이벤트 구독	다음 이벤트를 선택하세요. -incident.acknowledged -incident.annotated -incident.custom_field_values.updated -incident.delegated -incident.escalated -incident.priority_updated -incident.reassigned -incident.reopened -incident.resolved -incident.triggered -incident.unacknowledged
   사용자 지정 헤더	Add custom header를 클릭하고, DD-API-KEY 을(를) 이름으로 입력하고, 값으로 Datadog API 키를 입력합니다. 원할 경우, 웹훅에서 전송되는 모든 PagerDuty 인시던트에 환경을 추가하기 위해 이름을 dd_env (으)로 하여 원하는 환경 값으로 추가 사용자 지정 헤더를 생성할 수 있습니다.

4. 웹훅을 저장하려면 Add Webhook을 클릭합니다.

DORA Metrics 제품에서 실패의 심각도는 PagerDuty의 인시던트 우선순위를 기준으로 결정됩니다.

참고: 웹훅 생성 시 새로운 시크릿이 생성되며 모든 웹훅 페이로드에 서명하는 데 사용됩니다. 하지만 인증은 API 키를 사용하므로 해당 시크릿은 통합 동작에 필요하지 않습니다.

PagerDuty 서비스를 Datadog 서비스에 매핑

특정 PagerDuty 서비스에 대한 인시던트 이벤트를 수신하면 Datadog은 트리거된 Datadog 모니터와 Software Catalog를 기반으로 관련 Datadog 서비스와 팀을 찾으려고 시도합니다.

매칭 알고리즘은 다음 단계로 동작합니다.

1. PagerDuty 인시던트 이벤트가 Datadog 모니터에서 트리거된 경우:

   • 모니터가 다중 경고 모드에 있는 경우, 인시던트 메트릭과 이벤트는 경고 그룹의 env, service, team와 함께 전송됩니다.
   • 모니터에 env, service 또는 team에 대한 태그가 있는 경우:
     • env: 모니터에 단일 env 태그가 있는 경우, 인시던트 메트릭과 이벤트는 환경과 함께 전송됩니다.
     • service: 모니터에 하나 이상의 service 태그가 있는 경우, 인시던트 메트릭과 이벤트는 제공된 서비스와 함께 전송됩니다.
     • team: 모니터에 단일 team 태그가 있는 경우, 인시던트 메트릭과 이벤트는 팀과 함께 전송됩니다.

2. 인시던트의 서비스 URL이 Software Catalog의 모든 서비스에 대한 PagerDuty 서비스 URL과 일치하는 경우:

   • 단일 Datadog 서비스가 일치하는 경우, 인시던트 메트릭과 이벤트는 해당 서비스 및 팀과 함께 전송됩니다.
   • 여러 Datadog 서비스가 일치하는 경우, 인시던트 메트릭과 이벤트는 팀과 함께 전송됩니다.

   Datadog 서비스에 대한 PagerDuty 서비스 URL 설정에 대한 자세한 내용은 Software Catalog와 통합 사용을 참조하세요.

3. 인시던트의 PagerDuty 서비스 이름이 Software Catalog의 서비스 이름과 일치하는 경우, 인시던트 메트릭과 이벤트는 해당 서비스 및 팀과 함께 전송됩니다.

4. 인시던트의 PagerDuty 팀 이름이 Software Catalog의 팀 이름과 일치하는 경우, 인시던트 메트릭과 이벤트는 해당 팀과 함께 전송됩니다.

5. 인시던트의 PagerDuty 서비스 이름이 Software Catalog의 팀 이름과 일치하는 경우, 인시던트 메트릭과 이벤트는 해당 팀과 함께 전송됩니다.

6. 지금까지 일치하는 항목이 없는 경우, 인시던트 메트릭과 이벤트는 인시던트에 제공된 PagerDuty 서비스 및 PagerDuty 팀과 함께 전송됩니다.

직접 실패 이벤트를 보내려면 DORA Metrics API를 사용하세요. 실패 이벤트는 변경 실패율 및 복구 시간을 계산하는 데 사용됩니다.

실패가 해결되었음을 표시하기 위해 실패 이벤트에 finished_at 속성을 포함하세요. 실패 시작 시점과 해결 시점 모두 이벤트를 전송할 수 있습니다. 실패 이벤트는 env, service 및 started_at 속성 조합으로 매칭됩니다.

요구 사항

• datadog-ci CLI / API가 DORA 설정에서 Failures 이벤트 데이터 소스로 활성화되어 있어야 합니다.
• 필수 속성은 다음과 같습니다.
  • services 또는 team(최소 하나는 존재해야 함)
  • started_at

실패 이벤트에 다음 속성을 선택적으로 추가할 수 있습니다.

• finished_at: 해결된 실패에 사용.**.복구 시간 계산에 필요
• id: 실패 식별에 사용. 이 속성은 사용자가 생성한 속성입니다. 지정하지 않으면 엔드포인트는 Datadog가 생성한 UUID를 반환합니다.
• name : 실패를 설명합니다.
• severity
• env : DORA Metrics 페이지에서 환경별로 DORA 메트릭을 필터링합니다.
• repository_url
• commit_sha
• version
• custom_tags: key:value DORA Metrics 페이지에서 이벤트를 필터링하는 데 사용할 수 있는 형식의 태그입니다.

전체 사양 및 추가 코드 샘플은 DORA Metrics API 참조 설명서를 참조하세요.

API(cURL) 예제

다음 구성을 위해 <DD_SITE>를 으로 바꿉니다.

curl -X POST "https://api.<DD_SITE>/api/v2/dora/failure" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "DD-API-KEY: ${DD_API_KEY}" \
  -d @- << EOF
  {
    "data": {
      "attributes": {
        "services": ["shopist"],
        "team": "shopist-devs",
        "started_at": 1693491974000000000,
        "finished_at": 1693491984000000000,
        "git": {
          "commit_sha": "66adc9350f2cc9b250b69abddab733dd55e1a588",
          "repository_url": "https://github.com/organization/example-repository"
        },
        "env": "prod",
        "name": "Web server is down failing all requests",
        "severity": "High",
        "version": "v1.12.07",
        "custom_tags": ["department:engineering", "app_type:backend"]
      }
    }
  }
EOF