본문 바로가기
WIKI 기술 지식 베이스

Kubernetes에서 단일 단계 APM 계측 (Single Step APM Instrumentation on Kubernetes)

원문 보기 위키 갱신

Kubernetes 환경에서는 APM용 단일 단계 계측(SSI, Single Step Instrumentation)을 사용하면 Datadog Agent를 설치하고 Datadog SDK로 애플리케이션을 계측하는 작업을 한 단계로 끝낼 수 있어요.

출처: 문서

본문

개요

Kubernetes 환경에서는 APM용 단일 단계 계측(SSI)을 사용하면 Datadog Agent를 설치하고 Datadog SDK로 애플리케이션을 계측하는 작업을 한 단계로 끝낼 수 있어요.

AI 코딩 에이전트에 dd-apm 스킬을 설치해 안내에 따라 APM을 설정하세요.

npx skills add https://github.com/datadog-labs/agent-skills --skill dd-apm --full-depth -y

요구 사항

애플리케이션에서 APM 활성화

참고: 단일 단계 계측은 Datadog Agent가 설치된 네임스페이스의 애플리케이션은 계측하지 않아요. 애플리케이션이 실행되지 않는 별도의 네임스페이스에 Agent를 설치하세요.

클러스터 전체에서 단일 단계 계측을 활성화하면 지원되는 언어로 작성된 모든 애플리케이션의 트레이스가 자동으로 전송돼요.

참고: 특정 네임스페이스나 파드만 계측하려면 "고급 옵션"의 워크로드 타기팅을 참조하세요.

SSI를 활성화하려면 다음 명령을 사용하고 아래 항목을 바꿔요:

예시는 apm.instrumentation.enabled: true로 SSI를 활성화하고 datadog 네임스페이스를 사용해요. Agent가 다른 곳에 설치되어 있으면 네임스페이스를 바꾸세요.

Datadog Operator

  1. Datadog Operator를 설치하고 API 키를 담은 secret을 생성해요:

    helm repo add datadog https://helm.datadoghq.com
helm repo update
helm install datadog-operator datadog/datadog-operator --namespace datadog --create-namespace
kubectl create secret generic datadog-secret --from-literal api-key=<YOUR_DD_API_KEY> -n datadog

  2. APM 계측을 활성화하는 datadog-agent.yaml 파일을 생성해요:

    kind: "DatadogAgent"
apiVersion: "datadoghq.com/v2alpha1"
metadata:
  name: "datadog"
  namespace: "datadog"
spec:
  global:
    clusterName: "<YOUR_CLUSTER_NAME>"
    site: "<DATADOG_SITE>"
    credentials:
      apiSecret:
        secretName: "datadog-secret"
        keyName: "api-key"
  features:
    apm:
      instrumentation:
        enabled: true

최신 버전 대신 특정 SDK 버전을 고정하려면 ddTraceVersions가 있는 targets 블록을 추가해요. 전체 스키마는 "특정 워크로드 타기팅"을 참조하세요.

  1. Agent를 배포해요:

    kubectl apply -f datadog-agent.yaml

기존 Operator 설치를 업데이트하려면 datadog-agent.yaml에 SSI 구성을 추가하고 kubectl -n datadog apply -f datadog-agent.yaml로 다시 적용해요.

Helm

  1. Datadog Helm 저장소를 추가하고, datadog 네임스페이스를 생성하고, API 키를 담은 secret을 생성해요:

    helm repo add datadog https://helm.datadoghq.com
helm repo update
kubectl create namespace datadog
kubectl -n datadog create secret generic datadog-secret --from-literal api-key=<YOUR_DD_API_KEY>

  2. APM 계측을 활성화하는 datadog-values.yaml 파일을 생성해요:

    datadog:
  site: "<DATADOG_SITE>"
  clusterName: "<YOUR_CLUSTER_NAME>"
  apiKeyExistingSecret: "datadog-secret"
  apm:
    instrumentation:
      enabled: true

최신 버전 대신 특정 SDK 버전을 고정하려면 ddTraceVersions가 있는 targets 블록을 추가해요. 전체 스키마는 "특정 워크로드 타기팅"을 참조하세요.

  1. Agent를 배포해요:

    helm install datadog-agent -f datadog-values.yaml datadog/datadog --namespace datadog

기존 Helm 설치를 업데이트하려면 datadog-values.yaml에 SSI 구성을 추가하고 helm upgrade -n datadog -f datadog-values.yaml <RELEASE_NAME> datadog/datadog를 실행해요.

Agent를 배포한 후 애플리케이션을 다시 시작해요.

참고: SSI는 계측된 애플리케이션에 약간의 시작 시간을 추가해요. 이 오버헤드가 사용 사례에 맞지 않으면 Datadog 지원에 문의하세요.

Datadog에서 구성 생성

UI를 통해 구성을 생성하려면 Kubernetes에 Datadog Agent 설치 페이지로 이동해 화면 안내에 따라 설치 방법과 API 키를 선택해요. Configure datadog-agent.yaml 섹션에서 Additional configuration > Application Observability로 이동해 APM Instrumentation을 켜요. 그런 다음 생성된 구성 파일로 Agent를 배포해요.

설치 확인

  1. Agent 파드가 실행 중인지 확인해요:

    kubectl get pods -n datadog

  2. Agent가 정상이고 APM Agent가 실행 중인지 확인해요. <AGENT_POD>를 노드 Agent 파드 이름으로 바꿔요:

    kubectl exec <AGENT_POD> -n datadog -- agent status

출력의 APM Agent 섹션을 확인해요.

  1. 주입이 계측된 애플리케이션 파드에 도달했는지 확인해요. <APP_POD>와 <APP_NAMESPACE>를 애플리케이션 파드와 그 네임스페이스로 바꿔요:

    kubectl get pod <APP_POD> -n <APP_NAMESPACE> -o jsonpath='{.spec.initContainers[*].name}'

출력에는 datadog-init-apm-inject와 계측된 각 언어에 대한 datadog-lib-<language>-init 컨테이너가 포함돼요.

  1. 애플리케이션이 트래픽을 받은 후 서비스가 APM 서비스 페이지에 나타나는지 확인해요. 몇 분 안에 나타나지 않으면 SSI 트러블슈팅 가이드를 참조하세요.

통합 서비스 태그 구성

통합 서비스 태그(UST)는 트레이스, 메트릭, 로그에 일관된 태그를 적용해 옵저버빌리티 데이터를 더 쉽게 탐색하고 연관 지을 수 있게 해줘요. UST는 자동 라벨 추출(권장), ddTraceConfigs를 통한 명시적 구성, 또는 배포 매니페스트에서 구성할 수 있어요.

경고: Remote Configuration을 사용하는 경우 자동 라벨 추출은 호환되지 않아요. ddTraceConfigs를 사용해 UST를 명시적으로 구성해야 해요.

(권장) 자동 라벨 추출로 UST 구성

SSI를 사용하면 개별 배포를 수정하지 않고도 파드 라벨과 메타데이터에서 UST 값을 자동으로 추출할 수 있어요. 이렇게 하려면 kubernetesResourcesLabelsAsTags를 구성해 기존 Kubernetes 라벨을 Datadog 서비스 태그로 매핑해요.

참고: 이 방법은 Remote Configuration과 호환되지 않아요. Remote Configuration을 사용한다면 "ddTraceConfigs로 UST 명시적 구성"을 참조하세요.

사전 요구 사항
구성 요소 최소 버전
datadog-agent 7.69
datadog-operator 1.16.0
datadog-helm-chart 3.120.0
구성

다음 예시의 app.kubernetes.io/name을 서비스 이름을 포함하는 라벨(예: service.kubernetes.io/name 또는 component)로 바꿔요. 이 방식으로 여러 라벨을 구성할 수 있어요.

datadog:
  # Kubernetes 라벨에서 서비스 이름 자동 추출
  kubernetesResourcesLabelsAsTags:
    pods:
      app.kubernetes.io/name: service     # 현대적인 Kubernetes 라벨
    deployments.apps:
      app.kubernetes.io/name: service
    replicasets.apps:
      app.kubernetes.io/name: service

  # 클러스터 전체에 환경 전역 설정
  tags:
    - "env:production"

  apm:
    instrumentation:
      enabled: true

이 구성으로 Datadog는 이 라벨을 포함하는 계측된 워크로드에 대해 app.kubernetes.io/name 라벨 값을 사용해 service 태그를 자동으로 설정해요.

ddTraceConfigs로 UST 명시적 구성

대부분의 경우 자동 구성으로 충분해요. 다만 특정 워크로드에 대한 설정을 세밀하게 제어해야 한다면 ddTraceConfigs를 사용해 라벨을 서비스 구성으로 명시적으로 매핑해요:

datadog:
  kubernetesResourcesLabelsAsTags:
    pods:
      app.kubernetes.io/name: service
    deployments.apps:
      app.kubernetes.io/name: service

  # 클러스터 전체에 환경 전역 설정
  tags:
    - "env:production"

  apm:
    instrumentation:
      enabled: true
      targets:
        - name: frontend-services
          podSelector:
            matchLabels:
              tier: frontend
          ddTraceConfigs:
            - name: DD_SERVICE       # 서비스 이름 명시적 덮어쓰기
              valueFrom:
                fieldRef:
                  fieldPath: metadata.labels['app.kubernetes.io/name']
            # DD_ENV는 위 클러스터 레벨 태그에서 상속
            # DD_VERSION은 이미지 태그에서 자동 추출

배포 매니페스트에서 UST 구성

설정이 UST 추출에 적합한 라벨을 사용하지 않는다면 환경 변수를 사용해 배포 매니페스트에서 UST를 직접 설정할 수 있어요. 이 방식은 각 배포를 개별적으로 수정해야 하지만 정밀한 제어를 제공해요.

전체 지침은 Kubernetes 서비스에 UST 설정을 참조하세요.

SDK 기반 제품 및 기능 활성화

SSI가 애플리케이션에 Datadog SDK를 로드하고 분산 트레이싱을 활성화한 후, SDK에 의존하는 추가 제품을 구성할 수 있어요:

제품 환경 변수
런타임 메트릭 DD_RUNTIME_METRICS_ENABLED
로그 주입 DD_LOGS_INJECTION
Continuous Profiler DD_PROFILING_ENABLED
Data Streams Monitoring DD_DATA_STREAMS_ENABLED
App and API Protection DD_APPSEC_ENABLED
Runtime Code Analysis (IAST) DD_IAST_ENABLED
Dynamic Instrumentation DD_DYNAMIC_INSTRUMENTATION_ENABLED
Data Jobs Monitoring DD_DATA_JOBS_ENABLED
Software Composition Analysis DD_APPSEC_SCA_ENABLED

참고: 모든 변수는 true 또는 false를 허용해요. DD_PROFILING_ENABLED는 또한 auto를 허용하며, auto는 적격 프로세스만 프로파일링하며 SSI에 권장돼요.

다음 설정 방법 중 하나를 사용해요:

  • 워크로드 타기팅으로 구성(권장):

기본적으로 단일 단계 계측은 모든 네임스페이스의 모든 서비스를 계측해요. 워크로드 타기팅을 사용해 계측을 특정 네임스페이스, 파드, 워크로드로 제한하고 커스텀 구성을 적용해요.

애플리케이션 구성에서 직접 환경 변수를 설정해 제품을 활성화해요.

고급 옵션

다음 고급 옵션을 사용해 단일 단계 계측이 환경에서 동작하는 방식을 커스터마이즈할 수 있어요. 이 설정은 선택 사항이며, 일반적으로 특수한 구성에서만 필요해요.

주입 모드 구성

SSI는 여러 주입 모드를 지원하며, 주입기와 APM 라이브러리 파일이 애플리케이션 컨테이너로 전달되는 방식을 제어해요. 일반적으로 이 설정을 수동으로 구성할 필요는 없어요. 파드 초기화 중에 상당한 시작 지연이나 예상보다 높은 리소스 사용(CPU, 메모리)이 관찰된다면 조정을 고려해보세요. 주입기 작동 방식에 대한 자세한 내용은 단일 단계 계측의 주입기 동작을 참조하세요.

모드 설명 요구 사항
init_container init 컨테이너를 사용해 주입기와 APM 라이브러리 파일을 애플리케이션 컨테이너로 복사해요. Helm Chart 또는 Datadog Operator로 배포된 Agent
csi 프리뷰. Datadog CSI 드라이버를 사용해 주입기와 APM 라이브러리 파일을 마운트해요. init 컨테이너 모드보다 파드 시작 시간을 줄여요. Agent 7.76.0+, CSI 드라이버 1.2.0+, Helm Chart 3.178.1+ 또는 Datadog Operator 1.25.0+

csi 모드를 사용하기 전에 Datadog CSI 드라이버를 설치하고 활성화해요. Helm으로 배포한다면 datadog-values.yaml에도 datadog.csi.enabled: true를 설정해요. 설치 단계와 GKE Autopilot 같은 환경별 요구 사항은 CSI 드라이버 문서를 참조하세요.

주입 모드를 전역으로 구성

Helm — 클러스터 전체에서 주입 모드를 설정하려면 datadog-values.yaml에 injectionMode를 추가해요:

datadog:
  apm:
    instrumentation:
      injectionMode: <mode>

지원 값: init_container, csi.

Datadog Operator — 클러스터 전체에서 주입 모드를 설정하려면 datadog-agent.yaml에 injectionMode를 추가해요:

features:
  apm:
    instrumentation:
      injectionMode: <mode>

지원 값: init_container, csi.

Datadog Operator 1.25.0 미만을 사용한다면 파드 어노테이션을 사용해 특정 파드의 주입 모드를 덮어써요.

파드별 주입 모드 구성

특정 파드의 주입 모드를 덮어쓰려면 파드 스펙에 다음 어노테이션을 추가해요:

metadata:
  annotations:
    admission.datadoghq.com/apm-inject.injection-mode: "<mode>"

지원 값: init_container, csi.

특정 워크로드 타기팅

기본적으로 SSI는 클러스터의 모든 네임스페이스의 모든 서비스를 계측해요. Agent 버전에 따라 다음 구성 방법 중 하나를 사용해 어떤 서비스를 어떻게 계측할지 세분화해요.

Agent v7.64+ (권장)

targets 라벨로 타기팅 블록을 만들어 계측할 워크로드와 적용할 구성을 지정해요.

각 타겟 블록에는 다음 키가 있어요:

키 설명
name 타겟 블록의 이름. 모니터링 상태에는 영향이 없고 메타데이터로만 사용돼요.
namespaceSelector 계측할 네임스페이스. 다음 중 하나 이상으로 지정해요: matchNames(네임스페이스 이름 목록), matchLabels({key,value} 쌍으로 정의된 라벨 목록), matchExpressions(네임스페이스 선택기 요구 사항 목록). 네임스페이스는 모든 기준을 충족해야 일치해요. 자세한 내용은 Kubernetes 선택기 문서를 참조하세요.
podSelector 계측할 파드. 다음 중 하나 이상으로 지정해요: matchLabels({key,value} 쌍으로 정의된 라벨 목록), matchExpressions(파드 선택기 요구 사항 목록). 파드는 모든 기준을 충족해야 일치해요. 자세한 내용은 Kubernetes 선택기 문서를 참조하세요.
ddTraceVersions 각 언어에 사용할 Datadog APM SDK 버전.
ddTraceConfigs 통합 서비스 태그 설정, 트레이싱 이외의 SDK 기반 제품 활성화, 기타 APM 설정 커스터마이징을 허용하는 APM SDK 구성.

구성해야 할 파일은 단일 단계 계측을 활성화한 방식에 따라 달라져요:

  • Datadog Operator로 SSI를 활성화했다면 datadog-agent.yaml을 편집해요.
  • Helm으로 SSI를 활성화했다면 datadog-values.yaml을 편집해요.

참고: 타겟은 순서대로 평가되며, 첫 번째 일치가 우선해요.

예시 구성

특정 서비스를 선택하는 방법을 보여주는 다음 예시를 검토해보세요.

예시 1: 하나의 네임스페이스를 제외한 모든 네임스페이스 활성화

이 구성은:

  • jenkins 네임스페이스를 제외한 모든 네임스페이스에서 APM을 활성화해요.
    • 참고: 나열된 네임스페이스를 제외한 모든 네임스페이스에서 비활성화하려면 enabledNamespaces를 사용해요.
  • Datadog가 Java 애플리케이션을 기본 Java SDK로, Python 애플리케이션을 Python SDK v3.1.0으로 계측하도록 지시해요.
   apm:
     instrumentation:
       enabled: true
       disabledNamespaces:
         - "jenkins"
       targets:
         - name: "all-remaining-services"
           ddTraceVersions:
             java: "default"
             python: "3.1.0"

예시 2: 이름과 라벨로 일치하는 네임스페이스 하위 집합 계측

이 구성은 두 개의 타겟 블록을 생성해요:

  • 첫 번째 블록(login-service_namespace):
    • login-service 네임스페이스의 서비스에 대해 APM을 활성화해요.
    • 이 네임스페이스의 서비스를 기본 버전의 Java SDK로 계측하도록 지시해요.
    • 이 타겟 그룹에 환경 변수 DD_PROFILING_ENABLED를 설정해요.
  • 두 번째 블록(billing-service_apps):
    • app:billing-service 라벨이 있는 네임스페이스의 서비스에 대해 APM을 활성화해요.
    • 이 서비스 집합을 Python SDK v3.1.0으로 계측하도록 지시해요.
  apm:
    instrumentation:
      enabled: true
      targets:
        - name: "login-service_namespace"
          namespaceSelector:
            matchNames:
              - "login-service"
          ddTraceVersions:
            java: "default"
          ddTraceConfigs:
            - name: "DD_PROFILING_ENABLED"  ## 이 네임스페이스의 모든 서비스에 프로파일링 활성화
              value: "auto"
        - name: "billing-service_apps"
          namespaceSelector:
            matchLabels:
              app: "billing-service"
          ddTraceVersions:
            python: "3.1.0"

예시 3: 다른 트레이서로 다른 워크로드 계측

이 구성은:

  • 다음 라벨이 있는 파드에 대해 APM을 활성화해요:
    • app:db-user — db-user 애플리케이션을 실행하는 파드 표시.
    • webserver:routing — request-router 애플리케이션을 실행하는 파드 표시.
  • Datadog Tracer SDK의 기본 버전을 사용하도록 지시해요.
  • 각 타겟 그룹에 적용할 Datadog 환경 변수를 설정하고 SDK를 구성해요.
   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "db-user"
           podSelector:
             matchLabels:
               app: "db-user"
           ddTraceVersions:
             java: "default"
           ddTraceConfigs:   ## 일치하는 파드의 서비스에 설정되는 트레이스 구성
             - name: "DD_DATA_STREAMS_ENABLED"
               value: "true"
         - name: "user-request-router"
           podSelector:
             matchLabels:
               webserver: "user"
           ddTraceVersions:
             php: "default"

예시 4: 네임스페이스 내 특정 파드 계측

이 구성:

  • login-service 네임스페이스 내에서 app:password-resolver로 라벨이 지정된 파드에 대해 APM을 활성화해요.
  • Datadog Java Tracer SDK의 기본 버전을 사용하도록 지시해요.
  • 이 타겟에 적용할 Datadog 환경 변수를 설정해요.
   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "login-service-namespace"
           namespaceSelector:
             matchNames:
               - "login-service"
           podSelector:
             matchLabels:
               app: "password-resolver"
           ddTraceVersions:
             java: "default"
           ddTraceConfigs:
             - name: "DD_PROFILING_ENABLED"
               value: "auto"

예시 5: matchExpressions를 사용한 파드 하위 집합 계측

이 구성은 app=app1 또는 app=app2 라벨이 있는 파드를 제외한 모든 파드에 대해 APM을 활성화해요.

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "default-target"
           podSelector:
               matchExpressions:
                 - key: app
                   operator: NotIn
                   values:
                   - app1
                   - app2

예시 6: ddTraceConfigs로 추가 제품 활성화

이 구성은 ddTraceConfigs를 사용해 필요한 환경 변수를 설정함으로써 web-apps 네임스페이스의 서비스에 대해 App and API Protection (AAP)과 Continuous Profiler를 활성화해요:

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "web-apps-with-security"
           namespaceSelector:
             matchNames:
               - "web-apps"
           ddTraceVersions:
             java: "default"
             python: "default"
           ddTraceConfigs:
             - name: "DD_APPSEC_ENABLED"
               value: "true"
             - name: "DD_PROFILING_ENABLED"
               value: "auto"

SSI를 통해 활성화할 수 있는 전체 제품 목록은 "SDK 기반 제품 및 기능 활성화"를 참조하세요.

Agent <=v7.63 (레거시)

네임스페이스에 대한 계측 활성화 또는 비활성화

특정 네임스페이스의 애플리케이션에 대해 계측을 활성화하거나 비활성화할 수 있어요. enabledNamespaces 또는 disabledNamespaces 중 하나만 설정할 수 있으며 둘 다는 안 돼요.

구성해야 할 파일은 단일 단계 계측을 Datadog Operator 또는 Helm으로 활성화했는지에 따라 달라져요:

Datadog Operator

특정 네임스페이스의 계측을 활성화하려면 datadog-agent.yaml에 enabledNamespaces 구성을 추가해요:

   features:
     apm:
       instrumentation:
         enabled: true
         enabledNamespaces: # 계측할 네임스페이스 추가
           - default
           - applications

특정 네임스페이스의 계측을 비활성화하려면 datadog-agent.yaml에 disabledNamespaces 구성을 추가해요:

   features:
     apm:
       instrumentation:
         enabled: true
         disabledNamespaces: # 계측하지 않을 네임스페이스 추가
           - default
           - applications

Helm

특정 네임스페이스의 계측을 활성화하려면 datadog-values.yaml에 enabledNamespaces 구성을 추가해요:

   datadog:
      apm:
        instrumentation:
          enabled: true
          enabledNamespaces: # 계측할 네임스페이스 추가
             - namespace_1
             - namespace_2

특정 네임스페이스의 계측을 비활성화하려면 datadog-values.yaml에 disabledNamespaces 구성을 추가해요:

   datadog:
      apm:
        instrumentation:
          enabled: true
          disabledNamespaces: # 계측하지 않을 네임스페이스 추가
            - namespace_1
            - namespace_2
SDK 버전 지정

참고: Datadog Cluster Agent v7.52.0+부터 지정한 SDK를 기반으로 애플리케이션의 하위 집합을 자동으로 계측할 수 있어요.

Datadog SDK와 그 버전을 지정해 해당 언어로 작성된 애플리케이션을 자동으로 계측해요. 다음 두 가지 방식으로 구성할 수 있으며, 다음 우선순위 순서로 적용돼요:

  1. 서비스 레벨에서 지정, 또는
  2. 클러스터 레벨에서 지정.

기본값: 라이브러리 버전을 지정하지 않으면 지원되는 언어로 작성된 애플리케이션이 최신 SDK 버전으로 자동 계측돼요.

서비스 레벨에서 지정

특정 파드의 애플리케이션을 자동으로 계측하려면 파드 스펙에 애플리케이션에 맞는 언어 어노테이션과 라이브러리 버전을 추가해요:

언어 파드 어노테이션
Java admission.datadoghq.com/java-lib.version: "<CONTAINER IMAGE TAG>"
Node.js admission.datadoghq.com/js-lib.version: "<CONTAINER IMAGE TAG>"
Python admission.datadoghq.com/python-lib.version: "<CONTAINER IMAGE TAG>"
.NET admission.datadoghq.com/dotnet-lib.version: "<CONTAINER IMAGE TAG>"
Ruby admission.datadoghq.com/ruby-lib.version: "<CONTAINER IMAGE TAG>"
PHP admission.datadoghq.com/php-lib.version: "<CONTAINER IMAGE TAG>"

<CONTAINER IMAGE TAG>를 원하는 라이브러리 버전으로 바꿔요. 사용 가능한 버전은 각 언어의 Datadog 컨테이너 레지스트리와 트레이서 소스 저장소에 나열돼요:

주의: latest 태그는 주요 라이브러리 릴리스가 호환성을 깨는 변경을 도입할 수 있으므로 주의해서 사용해요.

예를 들어 Java 애플리케이션을 자동으로 계측하려면:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    # ...
spec:
  template:
    metadata:
      annotations:
        admission.datadoghq.com/java-lib.version: "<CONTAINER IMAGE TAG>"
    spec:
      containers:
        - # ...

클러스터 레벨에서 지정

어노테이션을 사용해 특정 파드에 대해 자동 계측을 활성화하지 않았다면 SSI 구성을 사용해 전체 클러스터에서 계측할 언어를 지정할 수 있어요. apm.instrumentation.libVersions가 설정되면 지정된 언어로 작성된 애플리케이션만 지정된 라이브러리 버전으로 계측돼요.

구성해야 할 파일은 단일 단계 계측을 Datadog Operator 또는 Helm으로 활성화했는지에 따라 달라져요:

Datadog Operator

예를 들어 .NET, Python, Node.js 애플리케이션을 계측하려면 datadog-agent.yaml 파일에 다음 구성을 추가해요:

   features:
     apm:
       instrumentation:
         enabled: true
         libVersions: # 설정할 라이브러리와 버전 추가
            dotnet: "x.x.x"
            python: "x.x.x"
            js: "x.x.x"

Helm

예를 들어 .NET, Python, Node.js 애플리케이션을 계측하려면 datadog-values.yaml 파일에 다음 구성을 추가해요:

   datadog:
     apm:
       instrumentation:
         enabled: true
         libVersions: # 설정할 라이브러리와 버전 추가
            dotnet: "x.x.x"
            python: "x.x.x"
            js: "x.x.x"

기본 이미지 레지스트리 변경

Datadog은 계측 라이브러리 이미지를 gcr.io, Docker Hub, Amazon ECR에 게시해요:

언어 gcr.io hub.docker.com gallery.ecr.aws
Java gcr.io/datadoghq/dd-lib-java-init hub.docker.com/r/datadog/dd-lib-java-init gallery.ecr.aws/datadog/dd-lib-java-init
Node.js gcr.io/datadoghq/dd-lib-js-init hub.docker.com/r/datadog/dd-lib-js-init gallery.ecr.aws/datadog/dd-lib-js-init
Python gcr.io/datadoghq/dd-lib-python-init hub.docker.com/r/datadog/dd-lib-python-init gallery.ecr.aws/datadog/dd-lib-python-init
.NET gcr.io/datadoghq/dd-lib-dotnet-init hub.docker.com/r/datadog/dd-lib-dotnet-init gallery.ecr.aws/datadog/dd-lib-dotnet-init
Ruby gcr.io/datadoghq/dd-lib-ruby-init hub.docker.com/r/datadog/dd-lib-ruby-init gallery.ecr.aws/datadog/dd-lib-ruby-init
PHP gcr.io/datadoghq/dd-lib-php-init hub.docker.com/r/datadog/dd-lib-php-init gallery.ecr.aws/datadog/dd-lib-php-init

Datadog Cluster Agent 구성의 DD_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY 환경 변수는 Admission Controller가 사용하는 레지스트리를 지정해요. 기본값은 gcr.io/datadoghq예요.

이를 docker.io/datadog, public.ecr.aws/datadog로 바꾸거나, 이미지를 로컬 컨테이너 레지스트리에서 호스팅하는 경우 다른 URL로 바꿔 다른 레지스트리에서 SDK를 가져올 수 있어요.

컨테이너 레지스트리 변경 지침은 컨테이너 레지스트리 변경을 참조하세요.

프라이빗 컨테이너 레지스트리 사용

조직에서 공개 레지스트리(gcr.io, docker.io, public.ecr.aws 등)에서 직접 풀하는 것을 허용하지 않는다면, 필요한 Datadog 이미지를 내부에서 호스팅하고 Admission Controller가 이를 사용하도록 구성할 수 있어요.

프라이빗 컨테이너 레지스트리에서 SSI를 사용하려면:

  1. 다음 지침에 따라 Datadog 컨테이너 이미지를 프라이빗 레지스트리로 미러링해요.

계측 중인 언어에 대한 이미지만 필요해요. 어떤 이미지가 필요한지 확실하지 않다면, 대부분의 사용 사례를 포괄하는 다음 기준 이미지를 확인하세요:

  • apm-inject
  • dd-lib-java-init
  • dd-lib-python-init
  • dd-lib-dotnet-init
  • dd-lib-php-init
  • dd-lib-ruby-init
  • dd-lib-js-init

이 이미지는 gcr.io, Docker Hub, Amazon ECR Public Gallery에서 찾을 수 있어요.

  1. 구성에 따라 이미지에 태그를 지정해요.

미러링한 버전은 워크로드에 구성된 버전과 일치해야 하며, 이는 다음 중 한 가지 방식으로 설정될 수 있어요:

  • Agent 구성에서 ddTraceVersions를 사용해 전역으로, 또는
  • admission.datadoghq.com/java-lib.version 같은 어노테이션을 사용해 파드별로.

버전이 명시적으로 구성되지 않으면 기본 버전(0)이 사용돼요.

예를 들어:

apm:
  instrumentation:
    enabled: true
    targets:
      - name: "default-target"
        ddTraceVersions:
          java: "1"
          python: "3"

이 구성에는 다음 이미지 태그가 필요해요:

  • apm-inject:0
  • dd-lib-java-init:1
  • dd-lib-python-init:3
  1. 프라이빗 레지스트리를 사용하도록 Cluster Agent 구성을 업데이트해요.

Cluster Agent 구성에서 DD_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY 환경 변수를 프라이빗 레지스트리로 설정해요.

컨테이너 레지스트리 변경에 대한 자세한 내용은 컨테이너 레지스트리 변경을 참조하세요.

EKS에서 컨테이너 네트워크 인터페이스 사용

Calico 같은 CNI를 사용할 때 컨트롤 플레인 노드는 Datadog의 Admission Controller에 네트워크 연결을 시작할 수 없어 "Address is not allowed" 오류를 보고해요. 단일 단계 계측을 사용하려면 useHostNetwork: true 매개변수로 Datadog의 Cluster Agent를 수정해요.

datadog:
  ...

clusterAgent:
  useHostNetwork: true

  admissionController:
    ...

Agent에서 단일 단계 APM 계측 제거

특정 서비스, 호스트, VM 또는 컨테이너에 대해 트레이스 데이터를 수집하고 싶지 않다면 다음 단계를 완료해요:

특정 서비스에 대한 계측 제거

특정 서비스에 대한 APM 계측을 제거하고 트레이스 전송을 중지하려면 다음 중 하나를 수행할 수 있어요:

계측 규칙으로 특정 워크로드 타기팅(권장)

계측 규칙(Agent v7.64+에서 사용 가능)을 사용하면 특정 애플리케이션에 대해 트레이싱을 활성화 및 비활성화할 수 있어요. 구성 세부 정보는 여기에서 확인하세요.

Datadog Admission Controller 사용

대안으로, 또는 계측 규칙을 지원하지 않는 Agent 버전의 경우 파드에 라벨을 추가해 파드 변형(mutation)을 비활성화할 수도 있어요.

주의: 다음 단계는 SSI를 비활성화하는 것 외에도 다른 변형 웹훅을 비활성화해요. 주의해서 사용하세요.

  1. 파드 스펙에 admission.datadoghq.com/enabled: 라벨을 "false"로 설정해요: 
    spec:
  template:
    metadata:
      labels:
        admission.datadoghq.com/enabled: "false"
  2. 구성을 적용해요: 
    kubectl apply -f /path/to/your/deployment.yaml
  3. 계측을 제거하려는 서비스를 다시 시작해요.

인프라의 모든 서비스에 대해 APM 제거

트레이스 생성을 중지하려면 APM을 제거하고 인프라를 다시 시작해요:

구성해야 할 파일은 단일 단계 계측을 Datadog Operator 또는 Helm으로 활성화했는지에 따라 달라져요:

Datadog Operator

  1. datadog-agent.yaml에서 instrumentation.enabled=false를 설정해요:

    features:
  apm:
    instrumentation:
      enabled: false

  2. 업데이트된 구성 파일로 Datadog Agent를 배포해요:

    kubectl apply -f /path/to/your/datadog-agent.yaml

Helm

  1. datadog-values.yaml에서 instrumentation.enabled=false를 설정해요:

    datadog:
  apm:
    instrumentation:
      enabled: false

  2. 다음 명령을 실행해요:

    helm upgrade datadog-agent -f datadog-values.yaml datadog/datadog

모범 사례

SSI를 활성화하면 클러스터의 모든 지원되는 프로세스가 자동으로 계측되어 몇 분 안에 트레이스 생성이 시작돼요.

APM이 활성화되는 위치를 제어하고 오버헤드를 줄이려면 다음 모범 사례를 고려해요.

제어된 APM 배포를 위한 옵트인 라벨 사용

기본 계측 vs. 옵트인 계측

모드 동작 사용 시기
기본 클러스터의 모든 지원되는 프로세스가 계측돼요. 소규모 클러스터 또는 프로토타입.
옵트인 계측 규칙을 사용해 계측을 특정 네임스페이스나 파드로 제한해요. 프로덕션 클러스터, 단계적 배포, 또는 비용에 민감한 사용 사례.

예시: 특정 파드에 대한 계측 활성화

  1. 배포 메타데이터와 파드 템플릿 모두에 의미 있는 라벨(예: datadoghq.com/apm-instrumentation: "enabled")을 추가해요.

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: checkout-api
  labels:
    app: checkout-api
    datadoghq.com/apm-instrumentation: "enabled"   # 옵트인 라벨 (클러스터 전체)
spec:
  replicas: 3
  selector:
    matchLabels:
      app: checkout-api
  template:
    metadata:
      labels:
        app: checkout-api
        datadoghq.com/apm-instrumentation: "enabled"   # 옵트인 라벨은 *템플릿*에도 있어야 함
        # 통합 서비스 태그 (권장)
        tags.datadoghq.com/service: "checkout-api"
        tags.datadoghq.com/env:     "prod"
        tags.datadoghq.com/version: "2025-06-10"
    spec:
      containers:
        - name: api
          image: my-registry/checkout:latest
          ports:
            - containerPort: 8080

  2. Datadog Agent Helm 구성에서 SSI를 활성화하고 podSelector를 사용해 일치하는 옵트인 라벨이 있는 파드에만 주입해요.

      apm:
    instrumentation:
      enabled: true
      targets:
        - name: apm-instrumented
          podSelector:
            matchLabels:
              datadoghq.com/apm-instrumentation: "enabled"

추가 예시는 계측 규칙을 참조하세요.

로드되는 Datadog SDK 제어

Agent Helm 구성의 ddTraceVersions를 사용해 Datadog SDK의 언어와 버전을 모두 제어해요. 이렇게 하면 불필요한 SDK 다운로드를 방지해 init 컨테이너의 용량(footprint)을 최소화하고, 이미지 크기를 줄이며, 더 신중한 트레이서 업그레이드(예: 규정 준수 요구 사항 충족 또는 디버깅 단순화)를 가능하게 해요.

예시: 네임스페이스에 Java SDK 지정

login-service 네임스페이스에서는 Java 애플리케이션만 실행돼요. 다른 SDK를 다운로드하지 않으려면 해당 네임스페이스를 타기팅하고 Java SDK 버전 1.48.2만 주입하도록 Agent를 구성해요.

targets:
  - name: login-service
    namespaceSelector:
      matchNames: ["login-service"]
    ddTraceVersions:
      java: "1.48.2"    # 버전 고정

기본 구성

파드가 어떤 ddTraceVersions 규칙과도 일치하지 않으면 기본 타겟이 적용돼요.

targets:
  - name: default-target          # 덮어쓰기가 *없는* 모든 파드에 태그
    ddTraceVersions:
      java:   "1"   # 최신 v1.x 유지
      python: "3"   # 최신 v3.x 유지
      js:     "5"   # NodeJS
      php:    "1"
      dotnet: "3"

트러블슈팅

SSI로 APM을 활성화하는 데 문제가 발생하면 SSI 트러블슈팅 가이드를 참조하세요.

더 알아보기 (Learn more)