동적 계측 (Dynamic Instrumentation)

원문 보기 위키 갱신 2026.10.05

재시작 없이 실행 중인 프로덕션 시스템에 계측을 추가해 코드의 모든 위치에서 메트릭, 스팬, 태그를 수집해요.

출처: 문서

본문

개요 (Overview)

Dynamic Instrumentation을 사용하면 재시작이나 코드 변경 없이 실행 중인 프로덕션 시스템에 메트릭, 스팬, 스팬 태그를 추가할 수 있어요. 여기에는 서드파티 라이브러리도 포함돼요.

자동 완성과 검색을 사용하려면 미리보기에 옵트인하세요.

참고: Dynamic Instrumentation은 Azure App Services 또는 서버리스 환경과 호환되지 않아요.

요구 사항 (Requirements)

Datadog SDK

Java 언어 사용자:

Datadog Java SDK (JDK 8 이상)
- 앱 내(in-app) 활성화 최소 버전: 1.48.0
- 수동 활성화 최소 버전: 1.34.0
- Kotlin 코루틴은 지원하지 않아요.

Python 언어 사용자:

Datadog Python SDK (ddtrace)
- 앱 내(in-app) 활성화 최소 버전: 3.10.0
- 수동 활성화 최소 버전: 2.2.0

.NET 언어 사용자:

Datadog .NET SDK (.NET Framework 또는 .NET Core)
- 앱 내(in-app) 활성화 최소 버전: 3.29.0
- 수동 활성화 최소 버전: 2.54.0

PHP 언어 사용자:

Datadog PHP SDK (dd-trace-php), 최소 버전 1.5.0
- 파일 및 줄 계측은 지원되지 않아요.

Datadog 구성 (Datadog configuration)

Datadog Agent를 버전 7.49.0 이상으로 설치하세요.
service, env, version 태그로 Unified Service Tagging을 구성하세요.
Agent에서 Remote Configuration을 활성화하세요.
(권장) Source Code Integration을 설정하세요.

권한 (Permissions)

Dynamic Instrumentation을 사용하려면 다음 권한이 필요해요:

Dynamic Instrumentation Read Configuration (debugger_read): Dynamic Instrumentation 페이지에 접근하는 데 필요해요.
다음 쓰기 권한 중 하나:
- Dynamic Instrumentation Write Configuration (debugger_write): 모든 환경에서 계측을 만들거나 수정하는 데 필요해요.
- Dynamic Instrumentation Write Pre-Prod (debugger_write_preprod): 알려진 사전 프로덕션 환경(예: 스테이징 또는 QA)에서만 계측을 만들거나 수정하는 데 필요해요.

역할과 사용자에게 역할을 할당하는 방법에 대한 자세한 내용은 Role Based Access Control을 참고하세요.

Dynamic Instrumentation 활성화 (Enable Dynamic Instrumentation)

정보 Dynamic Instrumentation과 Live Debugger는 서비스 및 환경별로 동일한 활성화 상태를 공유해요. 하나를 활성화하거나 비활성화하면 다른 하나도 활성화되거나 비활성화돼요. 두 제품은 별도의 권한과 Settings 페이지를 가져요.

Java, Python, .NET 언어 사용자: Dynamic Instrumentation을 앱 내(in-app) 또는 수동으로 활성화할 수 있어요.

앱 내 활성화 (권장) (Enable in-app - recommended)

두 가지 방법 중 하나로 앱 내에서 Dynamic Instrumentation을 활성화하세요:

Dynamic Instrumentation Settings 페이지에서 서비스와 환경을 활성화하세요.
계측을 만들면 선택한 서비스와 환경에서 Dynamic Instrumentation이 자동으로 활성화돼요.

수동 활성화 (Enable manually)

SDK가 앱 내 최소 버전보다 낮거나 Datadog UI 밖에서 활성화를 관리하려면 다음 단계를 따르세요.

Java 언어 사용자:

아직 APM이 활성화되지 않았다면 DD_APM_ENABLED=true를 설정하고 Agent가 포트 8126/TCP에서 수신하도록 구성하세요.

dd-java-agent.jar를 다운로드하세요:

Wget:

wget -O dd-java-agent.jar 'https://dtdg.co/latest-java-tracer'

cURL:

curl -Lo dd-java-agent.jar 'https://dtdg.co/latest-java-tracer'

Dockerfile:

ADD 'https://dtdg.co/latest-java-tracer' dd-java-agent.jar

Dynamic Instrumentation을 활성화한 상태로 서비스를 시작하세요. -javaagent 인자는 -jar보다 앞에 와야 해요:

명령 인자 (Command arguments):

java \
    -javaagent:dd-java-agent.jar \
    -Ddd.service=<YOUR_SERVICE> \
    -Ddd.env=<YOUR_ENVIRONMENT> \
    -Ddd.version=<YOUR_VERSION> \
    -Ddd.dynamic.instrumentation.enabled=true \
    -jar <YOUR_SERVICE>.jar <YOUR_SERVICE_FLAGS>

환경 변수 (Environment variables):

export DD_SERVICE=<YOUR_SERVICE>
export DD_ENV=<YOUR_ENV>
export DD_VERSION=<YOUR_VERSION>
export DD_DYNAMIC_INSTRUMENTATION_ENABLED=true
java \
    -javaagent:dd-java-agent.jar \
    -jar <YOUR_SERVICE>.jar <YOUR_SERVICE_FLAGS>

참고: JDK 18 이하에서 -parameters 플래그(Spring 6+, Spring Boot 3+, Scala의 기본값)로 컴파일된 클래스는 Method Parameters detected 오류와 함께 계측에 실패할 수 있어요.

서비스를 시작한 후 Dynamic Instrumentation 페이지를 여세요.

Python 언어 사용자:

아직 APM이 활성화되지 않았다면 DD_APM_ENABLED=true를 설정하고 Agent가 포트 8126/TCP에서 수신하도록 구성하세요.
ddtrace를 설치하세요:
```
pip install ddtrace
```

환경 변수 또는 코드로 Dynamic Instrumentation을 활성화하세요:

환경 변수 (Environment variables):

export DD_SERVICE=<YOUR_SERVICE>
export DD_ENV=<YOUR_ENV>
export DD_VERSION=<YOUR_VERSION>
export DD_DYNAMIC_INSTRUMENTATION_ENABLED=true
ddtrace-run python -m myapp.py

코드에서 (In code):

import os

os.environ["DD_DYNAMIC_INSTRUMENTATION_ENABLED"] = "true"

import ddtrace.auto  # this must be imported as soon as possible

서비스를 시작한 후 Dynamic Instrumentation 페이지를 여세요.

.NET 언어 사용자:

아직 APM이 활성화되지 않았다면 DD_APM_ENABLED=true를 설정하고 Agent가 포트 8126/TCP에서 수신하도록 구성하세요.

다음 환경 변수를 설정한 상태로 서비스를 시작하세요:

DD_SERVICE=<YOUR_SERVICE>
DD_ENV=<YOUR_ENV>
DD_VERSION=<YOUR_VERSION>
DD_DYNAMIC_INSTRUMENTATION_ENABLED=true

서비스를 시작한 후 Dynamic Instrumentation 페이지를 여세요.

PHP 언어 사용자:

아직 APM이 활성화되지 않았다면 DD_APM_ENABLED=true를 설정하고 Agent가 포트 8126/TCP에서 수신하도록 구성하세요.

다음 환경 변수를 설정한 상태로 서비스를 시작하세요:

DD_SERVICE=<YOUR_SERVICE>
DD_ENV=<YOUR_ENV>
DD_VERSION=<YOUR_VERSION>
DD_DYNAMIC_INSTRUMENTATION_ENABLED=true

서비스를 시작한 후 Dynamic Instrumentation 페이지를 여세요.

Dynamic Instrumentation 구성 (Configure Dynamic Instrumentation)

다음 환경 변수로 Dynamic Instrumentation을 구성하세요:

환경 변수	타입	설명
`DD_DYNAMIC_INSTRUMENTATION_ENABLED`	Boolean	`true`로 설정하면 Dynamic Instrumentation을 활성화.
`DD_SERVICE`	String	서비스 이름. 예: `web-backend`.
`DD_ENV`	String	환경 이름. 예: `production`.
`DD_VERSION`	String	서비스의 버전.
`DD_TAGS`	String	생성된 데이터에 적용할 태그. 쉼표로 구분된 `<key>:<value>` 목록이어야 해요. 예: `layer:api,team:intake`.

Java 언어 사용자 참고: DD_DYNAMIC_INSTRUMENTATION_ENABLED 대신 -Ddd.dynamic.instrumentation.enabled=true를 설정할 수도 있어요.

Dynamic Instrumentation 탐색 (Explore Dynamic Instrumentation)

Dynamic Instrumentation은 애플리케이션이 런타임에 수행하는 작업을 이해하는 데 도움을 줘요. 특정 코드 위치에 계측을 추가하면 코드를 변경하거나 재배포하지 않고도 애플리케이션에서 추가 원격 측정(telemetry)을 캡처할 수 있어요.

계측 사용 (Using instrumentations)

계측을 사용하면 프로그램 실행을 멈추지 않고 코드의 특정 지점에서 추가 원격 측정을 수집할 수 있어요.

동적 스팬, 스팬 태그, 메트릭은 소스 코드에 직접 사용자 정의 계측을 추가하는 것의 UI 기반 대안이에요. Datadog은 정의한 계측 구성을 받아 재시작 없이 실행 중인 서비스에 동적으로 적용해요.

Datadog은 Dynamic Instrumentation이 생성한 스팬, 태그, 메트릭을 실행 중인 애플리케이션의 다른 원격 측정과 마찬가지로 캡처하고 처리해요. 수동 사용자 정의 계측과 달리 Dynamic Instrumentation은 코드 변경, 배포, 서비스 재시작이 필요하지 않아요. 데이터 수집을 중지하려면 Datadog에서 계측을 비활성화하세요.

계측에서 민감한 데이터를 제거하려면 Sensitive data scrubbing을 참고하세요.

계측 만들기 (Creating an instrumentation)

모든 계측 유형은 동일한 초기 설정이 필요해요:

Dynamic Instrumentation 페이지로 이동하세요.
오른쪽 상단의 Create Instrumentation을 클릭하거나, 서비스의 점 3개 메뉴를 클릭하고 Add an instrumentation for this service를 선택하세요.
필드가 미리 채워지지 않은 경우 서비스, 런타임, 환경, 버전(선택)을 선택하세요.
Java, Python, .NET 사용자: 클래스와 메서드 또는 파일의 특정 코드 줄을 선택해 소스 코드에서 계측을 설정할 위치를 지정하세요. 자동 완성과 검색이 가능하면 이를 사용해 파일, 메서드, 기호를 찾으세요. PHP 사용자: 클래스와 메서드를 선택해 소스 코드에서 계측을 설정할 위치를 지정하세요. 자동 완성과 검색이 가능하면 이를 사용해 메서드나 기호를 찾으세요.

최상의 경험을 위해 Source Code Integration을 설정해 Datadog에서 코드를 직접 보고 IDE의 중단점처럼 계측 위치를 선택하세요.

각 계측 유형별 생성 단계는 아래 섹션을 참고하세요.

정보 동적 로그 계측은 Live Debugger에서 지원돼요. Live Debugger를 사용해 실행 중인 애플리케이션에서 로그와 변수 스냅샷을 실시간으로 캡처하세요.

동적 메트릭 만들기 (Creating dynamic metrics)

동적 메트릭은 실행될 때 메트릭을 방출해요. 동적 메트릭을 만들려면:

계측 유형으로 Metric을 선택하세요.
일반 계측 설정을 완료하세요(서비스, 환경, 위치 선택).
dynamic.instrumentation.metric.probe.가 접두사로 붙는 메트릭 이름을 지정하세요.
메트릭 유형(count, gauge, histogram)을 선택하세요.
Dynamic Instrumentation 표현식 언어를 사용해 메트릭 값을 선택하세요. 실행 컨텍스트의 모든 숫자 값(메서드 매개변수, 지역 변수, 클래스 필드, 숫자 값을 산출하는 표현식)을 사용할 수 있어요. count 메트릭의 경우 이는 선택 사항이며 생략하면 호출할 때마다 개수가 1씩 증가해요.

메트릭 계측은 구성된 환경 및 버전과 일치하는 모든 서비스 인스턴스에서 자동으로 활성화돼요. 메트릭 계측은 속도 제한이 없으며 메서드(또는 줄)가 호출될 때마다 실행돼요.

Dynamic Instrumentation은 다음 메트릭 유형을 지원해요:

Count: 지정된 메서드(또는 줄)가 실행된 횟수를 세어요. 변수 값을 사용해 개수를 증가시키도록 메트릭 표현식과 결합할 수 있어요.
Gauge: 변수의 마지막 값을 기반으로 게이지를 생성해요. 이 메트릭은 메트릭 표현식이 필요해요.
Histogram: 변수의 통계적 분포를 생성해요. 이 메트릭은 메트릭 표현식이 필요해요.

동적 스팬 만들기 (Creating dynamic spans)

동적 스팬은 메서드가 실행될 때 스팬을 방출해요. 동적 스팬을 만들려면:

계측 유형으로 Span을 선택하세요.
일반 계측 설정을 완료하세요(서비스, 환경, 버전, 위치 선택).

동적 스팬을 Custom Instrumentation으로 스팬 만들기의 대안으로 사용할 수 있어요. 메서드가 예외를 던지면 예외 세부 정보는 새로 생성된 스팬의 error 태그와 연결돼요.

동적 스팬 태그 만들기 (Creating dynamic span tags)

동적 스팬 태그는 기존 스팬에 태그 값을 추가해요. 활성(active) 스팬 또는 서비스 진입(service entry) 스팬에 태그를 추가할 수 있어요.

참고: 내부 스팬은 기본적으로 인덱싱되지 않으므로 APM에서 검색되지 않을 수 있어요.

동적 스팬 태그를 만들려면:

계측 유형으로 Span Tag를 선택하세요.
일반 계측 설정을 완료하세요(서비스, 환경, 버전, 위치 선택).
태그 이름을 지정하세요.
Dynamic Instrumentation 표현식 언어를 사용해 태그 값을 지정하세요.
선택적으로 Dynamic Instrumentation 표현식 언어를 사용해 조건을 정의하세요. 표현식이 true로 평가될 때만 태그가 추가돼요.
선택적으로 각각 고유한 이름, 표현식, 선택적 조건을 가진 추가 태그를 더하세요.

동적 스팬 태그를 Custom Instrumentation으로 코드에 태그 추가하기의 대안으로 사용할 수 있어요.