Docker에서 Single Step APM 계측 (Single Step APM Instrumentation on Docker)

원문 보기 위키 갱신 2026.10.05

Docker Linux 컨테이너에서 APM용 Single Step 계측(SSI)을 사용하면 추가 구성 없이 한 번의 단계로 Datadog 에이전트를 설치하고 애플리케이션을 계측할 수 있어요.

출처: 문서

본문

개요 (Overview)

Docker Linux 컨테이너에서 APM용 Single Step 계측(SSI)을 사용하면 추가 구성이 필요 없이 한 번의 단계로 Datadog 에이전트를 설치하고 애플리케이션을 계측할 수 있어요.

{% section %}에이전트로 APM 설정하기AI 코딩 에이전트에 dd-apm 스킬을 설치해 가이드에 따라 APM을 설정하세요.

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

{% /section %}

애플리케이션에서 APM 활성화하기 (Enable APM on your applications)

{% alert level="info" %} 진행하기 전에 SSI 호환성 가이드를 검토해 환경이 호환되는지 확인하세요. {% /alert %}

Docker Linux 환경에서 Datadog 에이전트를 설치하고 SSI를 활성화하려면 Docker 호스트(애플리케이션 컨테이너 내부가 아닌)에서 다음 명령을 실행해요.

호스트 에이전트를 설치하지 않고 Docker 계측 구성 요소를 설치해요:

DD_APM_INSTRUMENTATION_ENABLED=docker \
DD_NO_AGENT_INSTALL=true \
bash -c "$(curl -L https://install.datadoghq.com/scripts/install_script_agent7.sh)"

에이전트 컨테이너를 실행하거나 다시 배포해요. <YOUR_DD_API_KEY>를 Datadog API 키로 바꿔주세요:

docker run -d --name dd-agent \
  -e DD_API_KEY=<YOUR_DD_API_KEY> \
  -e DD_SITE="<YOUR_DATADOG_SITE>" \
  -e DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true \
  -e DD_APM_ENABLED=true \
  -e DD_APM_NON_LOCAL_TRAFFIC=true \
  -e DD_APM_RECEIVER_SOCKET=/var/run/datadog/apm.socket \
  -e DD_DOGSTATSD_SOCKET=/var/run/datadog/dsd.socket \
  -v /var/run/datadog:/var/run/datadog \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /proc/:/host/proc/:ro \
  -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
  -v /var/lib/docker/containers:/var/lib/docker/containers:ro \
  registry.datadoghq.com/agent:7

참고: 노드마다 Datadog 에이전트를 하나만 실행하세요. Datadog 에이전트 컨테이너가 이미 있다면 두 번째 에이전트를 시작하는 대신 이 설정으로 정의(또는 Docker Compose 파일)를 업데이트하고 다시 만드세요. 루트리스(rootless) Docker의 경우 docker_config.yaml에서 올바른 Docker 소켓을 설정하세요.

애플리케이션 컨테이너를 다시 만들어요.

계측은 컨테이너가 생성될 때 적용돼요. 그래서 docker stop과 docker start로 기존 컨테이너를 재시작해도 계측되지 않아요. 애플리케이션 컨테이너를 제거하고 다시 실행하세요.

{% alert level="info" %} SSI는 계측된 애플리케이션에 약간의 시작 시간을 추가해요. 이 오버헤드가 사용 사례에 맞지 않으면 Datadog 지원에 문의하세요. {% /alert %}

Datadog에서 명령 생성하기 (Generate the command from Datadog)

API 키와 사이트가 미리 채워진 명령을 얻으려면 Docker에 Datadog 에이전트 설치 페이지로 이동해요. Customize my agent install command 섹션에서 Additional configuration > Application Observability로 가서 APM Instrumentation을 켜요. 그런 다음 생성된 명령을 복사해 실행해요.

{% image source="https://docs.dd-static.net/images/tracing/trace_collection/docker-apm-instrumentation-toggle.938c8ca3f7550fba24ac50a6c4f8062d.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/docker-apm-instrumentation-toggle.938c8ca3f7550fba24ac50a6c4f8062d.png?auto=format&fit=max&w=850&dpr=2 2x" alt="The 'Customize your agent install command' section of in-app instructions for installing the Datadog Agent on Docker" /%}

SDK 트레이서 버전 설정하기 (Set SDK tracer versions)

기본적으로 Single Step 계측은 Datadog SDK의 최신 메이저 버전을 설치하고, 사용 가능해지면 마이너 업데이트를 자동으로 적용해요.

특정 버전을 고정하려면 구성 요소 설치 명령에 쉼표로 구분된 language:major 쌍을 가진 DD_APM_INSTRUMENTATION_LIBRARIES 변수를 추가해요. 사용 가능한 버전은 각 언어의 소스 저장소에 나열돼 있어요:

Java (java)
Node.js (js)
Python (python)
.NET (dotnet)
Ruby (ruby)
PHP (php)

Datadog의 드롭다운에서 버전을 선택할 수도 있어요: Docker에 Datadog 에이전트 설치 페이지에서 APM Instrumentation을 켠 뒤 Customize library versions를 클릭하세요.

{% image source="https://docs.dd-static.net/images/tracing/trace_collection/apm-instrumentation-version-pinning.5d47edec7389b8d323467110fa5ac203.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/tracing/trace_collection/apm-instrumentation-version-pinning.5d47edec7389b8d323467110fa5ac203.png?auto=format&fit=max&w=850&dpr=2 2x" alt="The 'Customize library versions' drop-down in the instructions for installing the Datadog Agent on Docker" /%}

설치 확인하기 (Verify the installation)

Docker 데몬이 Datadog 런타임을 사용하는지 확인해요:
```
docker system info --format '{{.DefaultRuntime}}'
```

출력은 dd-shim이어야 해요. runc이거나 다른 값이면 계측 구성 요소가 제대로 설치되지 않은 것이고, 에이전트가 정상이어도 애플리케이션이 계측되지 않아요. 설치 명령을 다시 실행하고 실행 당시 Docker 데몬이 실행 중이었는지 확인하세요.

에이전트 컨테이너가 실행 중인지 확인해요:
```
docker ps --filter name=dd-agent
```
에이전트가 정상이고 APM 에이전트가 실행 중인지 확인해요:
```
docker exec dd-agent agent status
```

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

애플리케이션 컨테이너가 Datadog 런타임을 사용하는지 확인해요. <CONTAINER_NAME>을 애플리케이션 컨테이너 이름 중 하나로 바꿔주세요:
```
docker inspect <CONTAINER_NAME> --format '{{.HostConfig.Runtime}}'
```
애플리케이션이 트래픽을 받은 후 서비스가 APM Services 페이지에 나타나는지 확인해요. 몇 분 내에 나타나지 않으면 SSI 문제 해결 가이드를 따라요.

통합 서비스 태그 구성하기 (Configure Unified Service Tags)

통합 서비스 태그(UST)는 트레이스, 메트릭, 로그 전반에 일관된 태그를 적용해 옵저버빌리티 데이터를 더 쉽게 탐색하고 상관시키도록 도와줘요. Docker 서비스에 UST 설정하기를 알아봐요.

SDK 종속 제품 및 기능 활성화하기 (Enable SDK-dependent products and features)

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

제품 (Product)	환경 변수 (Environment variable)
런타임 메트릭 (Runtime Metrics)	`DD_RUNTIME_METRICS_ENABLED`
로그 주입 (Log Injection)	`DD_LOGS_INJECTION`
연속 프로파일러 (Continuous Profiler)	`DD_PROFILING_ENABLED`
데이터 스트림 모니터링 (Data Streams Monitoring)	`DD_DATA_STREAMS_ENABLED`
앱 및 API 보호 (App and API Protection)	`DD_APPSEC_ENABLED`
런타임 코드 분석 (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도 허용하는데, 적격 프로세스만 프로파일링하며 SSI에 권장돼요.

제품을 활성화하려면 애플리케이션 구성에서 환경 변수를 설정하세요.

에이전트에서 Single Step APM 계측 제거하기 (Remove Single Step APM instrumentation from your Agent)

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

특정 서비스용 계측 제거하기 (Remove instrumentation for specific services)

특정 서비스에서 APM 계측을 제거하고 트레이스 전송을 중지하려면:

서비스 시작 명령에 DD_INSTRUMENT_SERVICE_WITH_APM 환경 변수를 추가해요:
```
docker run -e DD_INSTRUMENT_SERVICE_WITH_APM=false <service_start_command>
```
서비스를 재시작해요.

인프라의 모든 서비스에서 APM 제거하기 (Remove APM for all services on the infrastructure)

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

다음을 실행해요:
```
dd-container-install --uninstall
```
Docker를 재시작해요:
```
systemctl restart docker
```

또는 환경에 맞는 명령을 사용해요.

문제 해결 (Troubleshooting)

SSI로 APM을 활성화할 때 문제가 발생하면 SSI 문제 해결 가이드를 참고하세요.

더 알아보기 (Learn more)

도움이 되는 추가 문서, 링크, 아티클이에요:

런타임 메트릭 활성화하기