개요

Kubernetes 환경에서는 APM에 Single Step Instrumentation(SSI)을 사용하여 Datadog Agent를 설치하고 Datadog SDK를 사용해 애플리케이션을 한 단계 만에 계측하세요.

요구 사항

• Kubernetes v1.20+.
• Datadog Operator 배포를 위한 Helm.
• Datadog Agent 설치를 위한 Kubectl CLI.
• Single Step Instrumentation 호환성 가이드에 따라 확인된 환경 호환성.

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

클러스터 전체에서 Single Step Instrumentation을 활성화하려면 다음 단계를 따르세요. 이렇게 하면 지원되는 언어로 작성된 모든 애플리케이션에서 자동으로 트레이스를 전송합니다.

참고: 특정 네임스페이스 또는 포드만 계측하려면 고급 옵션의 워크로드 대상 지정을 참조하세요.

1. Datadog에서 Kubernetes에 Datadog Agent 설치 페이지로 이동합니다.

2. 화면의 지침에 따라 설치 방법을 선택하고, API 키를 선택하고 Operator 또는 Helm 리포지토리를 설정합니다.

3. 구성 datadog-agent.yaml 섹션에서 추가 구성 > Application Observability로 이동하여 APM Instrumentation을 켭니다.

4. 생성된 구성 파일을 사용하여 Agent를 배포합니다.

5. 애플리케이션을 재시작하세요.

Unified Service Tags 구성

Unified Service Tags(UST)는 트레이스, 메트릭, 로그에 일관된 태그를 적용해 탐색 및 관측 가능성 데이터 상호 연계가 간편합니다. UST는 자동 레이블 추출(권장)을 통해 구성할 수도 있고, ddTraceConfigs를 사용한 명시적 구성을 통하거나 배포 매니페스트에서 구성할 수도 있습니다.

(권장) 자동 레이블 추출을 통해 UST 구성

SSI를 사용하면 개별 배포를 수정하지 않고 자동으로 포드 레이블 및 메타데이터에서 UST 값을 추출할 수 있습니다. 이렇게 하려면 kubernetesResourcesLabelsAsTags가 기존 Kubernetes 레이블을 Datadog 서비스 태그로 매핑하도록 구성하세요.

참고: 이 방법은 Remote Configuration과 호환되지 않습니다. Remote Configuration을 사용하는 경우, ddTraceConfigs를 사용하여 명시적으로 UST 구성을 참조하세요.

전제 조건

구성

다음 예시의 app.kubernetes.io/name를 서비스 이름이 포함된 레이블로 교체하세요(예: service.kubernetes.io/name 또는 component). 이렇게 하면 레이블 여러 개를 구성할 수 있습니다.

datadog:
  # Automatically extract service names from Kubernetes labels
  kubernetesResourcesLabelsAsTags:
    pods:
      app.kubernetes.io/name: service     # Modern Kubernetes label
    deployments.apps:
      app.kubernetes.io/name: service
    replicasets.apps:
      app.kubernetes.io/name: service

  # Set environment globally for the entire cluster
  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

  # Set environment globally for the entire cluster
  tags:
    - "env:production"

  apm:
    instrumentation:
      enabled: true
      targets:
        - name: frontend-services
          podSelector:
            matchLabels:
              tier: frontend
          ddTraceConfigs:
            - name: DD_SERVICE       # Explicitly override service name
              valueFrom:
                fieldRef:
                  fieldPath: metadata.labels['app.kubernetes.io/name']
            # DD_ENV inherited from cluster-level tags above
            # DD_VERSION automatically extracted from image tags

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

설정에서 UST 추출에 적합한 레이블을 사용하지 않는 경우, 환경 변수를 사용해 배포 매니페스트에서 직접 UST를 설정할 수 있습니다. 이 방식으로 접근하려면 각 배포를 개별적으로 수정해야 하지만, 정밀한 제어가 가능합니다.

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

SDK 종속적 제품 및 기능 활성화

SSI가 애플리케이션에 Datadog SDK를 로드하고 분산 트레이싱을 활성화하고 나면 SDK에 의존하는 추가적인 제품을 구성할 수 있습니다.

Note: All variables accept true or false. DD_PROFILING_ENABLED also accepts auto, which profiles only eligible processes and is recommended for SSI.

다음 설정 방법 중 한 가지를 사용하세요.

• 워크로드 대상 지정을 사용하여 구성(권장):

  기본적으로 Single Step Instrumentation은 모든 네임스페이스의 모든 서비스를 계측합니다. 워크로드 대상 지정을 사용하여 계측을 특정 네임스페이스, 포드 또는 워크로드로만 제한하고 사용자 지정 구성을 적용하세요.

• 환경 변수 설정:

  애플리케이션 구성에서 직접 환경 변수를 설정하여 제품을 활성화합니다.

고급 옵션

다음 고급 옵션을 사용하여 Single Step Instrumentation이 환경에서 어떻게 동작할지 사용자 지정할 수 있습니다. 이러한 설정은 선택 사항이며 일반적으로 특수 설정에서만 필요합니다.

주입 모드 구성

SSI는 여러 가지 주입 모드를 지원합니다. 주입 모드는 인젝터와 APM 라이브러리 파일이 애플리케이션 컨테이너에 전송되는 방식을 제어합니다. 일반적으로 이 설정을 수동으로 구성할 필요가 없습니다. 포드 시작이 많이 지연되는 것이 눈에 띄거나, 포드 초기화 중에 리소스 사용량이(CPU, 메모리) 예상보다 많은 경우 이 설정을 조정하는 것을 고려해 보세요. 인젝터의 작동 원리에 관한 자세한 내용은 Single Step Instrumentation 사용 시 인젝터 동작을 참조하세요.

csi 모드를 사용하기 전에 Datadog CSI 드라이버를 설치하고 활성화하세요. Helm을 사용하여 배포하는 경우, datadog-values.yaml에서 datadog.csi.enabled: true도 설정하세요. 설치 단계 및 GKE Autopilot과 같은 환경별 요구 사항은 CSI 드라이버 설명서를 참조하세요.

전역적으로 주입 모드 구성

datadog:
  apm:
    instrumentation:
      injectionMode: <mode>

features:
  apm:
    instrumentation:
      injectionMode: <mode>

포드당 주입 모드 구성

특정 포드의 주입 모드를 재정의하려면 포드 사양에 다음 어노테이션 추가:

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

지원되는 값: init_container, csi.

특정 워크로드 대상

기본적으로 SSI는 클러스터의 모든 네임스페이스에 속한 모든 서비스를 계측합니다. Agent 버전에 따라 다음 구성 방법 중 하나를 사용하여 어느 서비스가 어떻게 계측될지 미세 조정하세요.

   apm:
     instrumentation:
       enabled: true
       disabledNamespaces:
         - "jenkins"
       targets:
         - name: "all-remaining-services"
           ddTraceVersions:
             java: "default"
             python: "3.1.0"

  apm:
    instrumentation:
      enabled: true
      targets:
        - name: "login-service_namespace"
          namespaceSelector:
            matchNames:
              - "login-service"
          ddTraceVersions:
            java: "default"
          ddTraceConfigs:
            - name: "DD_PROFILING_ENABLED"  ## profiling is enabled for all services in this namespace
              value: "auto"
        - name: "billing-service_apps"
          namespaceSelector:
            matchLabels:
              app: "billing-service"
          ddTraceVersions:
            python: "3.1.0"

   apm:
     instrumentation:
       enabled: true
       targets:
         - name: "db-user"
           podSelector:
             matchLabels:
               app: "db-user"
           ddTraceVersions:
             java: "default"
           ddTraceConfigs:   ## trace configs set for services in matching pods
             - name: "DD_DATA_STREAMS_ENABLED"
               value: "true"
         - name: "user-request-router"
           podSelector:
             matchLabels:
               webserver: "user"
           ddTraceVersions:
             php: "default"

   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"

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

   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"

   features:
     apm:
       instrumentation:
         enabled: true
         enabledNamespaces: # Add namespaces to instrument
           - default
           - applications

   features:
     apm:
       instrumentation:
         enabled: true
         disabledNamespaces: # Add namespaces to not instrument
           - default
           - applications

   datadog:
      apm:
        instrumentation:
          enabled: true
          enabledNamespaces: # Add namespaces to instrument
             - namespace_1
             - namespace_2

   datadog:
      apm:
        instrumentation:
          enabled: true
          disabledNamespaces: # Add namespaces to not instrument
            - namespace_1
            - namespace_2

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

   features:
     apm:
       instrumentation:
         enabled: true
         libVersions: # Add any libraries and versions you want to set
            dotnet: "x.x.x"
            python: "x.x.x"
            js: "x.x.x"

   datadog:
     apm:
       instrumentation:
         enabled: true
         libVersions: # Add any libraries and versions you want to set
            dotnet: "x.x.x"
            python: "x.x.x"
            js: "x.x.x"

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

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

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

다른 레지스트리에서 SDK를 가져오려면 이것을 docker.io/datadog, public.ecr.aws/datadog으로 변경하면 되고, 로컬 컨테이너 레지스트리에서 이미지를 호스팅하는 경우 다른 URL로 변경하면 됩니다.

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

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

조직이 퍼블릭 레지스트리(예: 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에 있습니다.

2. 구성에 따라 이미지를 태그합니다.

   미러링하는 버전이 워크로드에서 구성된 버전과 일치해야 하며, 이는 다음 중 한 가지 방법으로 설정할 수 있습니다.

   • ddTraceVersions를 사용하여 Agent 구성에서 전역적으로, 또는
   • 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

3. 프라이빗 레지스트리를 사용하려면 Cluster Agent 구성을 업데이트하세요.

   프라이빗 레지스트리를 사용하려면 Cluster Agent 구성에서 DD_ADMISSION_CONTROLLER_AUTO_INSTRUMENTATION_CONTAINER_REGISTRY 환경 변수를 설정하세요.

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

EKS에서 Container Network Interface 사용

Calico와 같은 CNI를 사용하는 경우,컨트롤 플레인 노드가 Datadog의 Admission Controller로의 네트워크 연결을 시작할 수 없고 “Address is not allowed(주소가 허용되지 않음)” 오류를 보고합니다. Single Step instrumentation을 사용하려면 Datadog의 Cluster Agent를 useHostNetwork: true 파라미터를 사용해 수정하세요.

datadog:
  ...

clusterAgent:
  useHostNetwork: true

  admissionController:
    ...

Agent에서 Single Step APM 계측 제거

특정 서비스, 호스트, VM 또는 컨테이너의 트레이스 데이터를 수집하지 않고자 하는 경우, 다음 단계를 따르세요.

특정 서비스의 계측 제거

특정 서비스에서 APM 계측을 제거하고 트레이스 보내기를 중단하려면 다음 중 한 가지 작업을 수행합니다.

특정 워크로드를 대상으로 지정하는 계측 규칙 사용(권장)

계측 규칙을 사용하면(Agent v7.64+에서 사용 가능) 특정 애플리케이션의 추적을 활성화 또는 비활성화할 수 있습니다. 여기에서 구성 세부 정보를 참조하세요.

Datadog Admission Controller 사용

대안으로, 또는 계측 규칙을 지원하지 않는 에이전트 버전인 경우, 포드에 레이블을 추가하여 포드 변형을 비활성화할 수도 있습니다.

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을 제거하고 인프라를 재시작:

구성해야 하는 파일은 Single Step Instrumentation을 Datadog Operator 또는 Helm 중 무엇으로 활성화했는지에 따라 다릅니다.

모범 사례

SSI를 활성화하고 나면 몇 분 안에 클러스터의 모든 지원되는 프로세스가 자동으로 계측되며 트레이스를 생성하기 시작합니다.

APM이 어디에서 활성화되는지 제어하고 오버헤드를 줄이려면 다음 모범 사례를 고려하세요.

targets:
  - name: login-service
    namespaceSelector:
      matchNames: ["login-service"]
    ddTraceVersions:
      java: "1.48.2"    # pin version

targets:
  - name: default-target          # tag any pod *without* an override
    ddTraceVersions:
      java:   "1"   # stay on latest v1.x
      python: "3"   # stay on latest v3.x
      js:     "5"   # NodeJS
      php:    "1"
      dotnet: "3"

문제 해결

SSI로 APM 활성화와 관련한 문제가 발생하는 경우, SSI 문제 해결 가이드를 참조하세요.

추가 자료

추가 유용한 문서, 링크 및 기사:

런타임 메트릭 활성화설명서 init 컨테이너 리소스 사용량에 관해 알아보기설명서 로컬 SDK 주입을 사용한 애플리케이션 계측설명서 Kubernetes에서 Single Step Instrumentation 구성학습 센터