PHP SDK 구성 (Configuring the PHP SDK)
PHP SDK를 코드와 함께 설정하고 Agent가 APM 데이터를 수집하도록 구성한 뒤, 필요에 따라 SDK를 원하는 대로 구성하는 방법을 안내해요. 여기에는 Unified Service Tagging 설정도 포함돼요.
출처: 문서
본문
런타임 구성을 확인하고 설정을 검증하려면 Datadog에서 서비스의 현재 구성을 확인하세요. APM Service Page로 이동해 Service Config를 클릭하고 SDK Configuration 탭을 선택하세요.
PHP 트레이서는 환경 변수와 INI 설정으로 구성할 수 있어요.
INI 설정은 예를 들어 php.ini 파일에서 전역적으로, 또는 특정 웹 서버나 가상 호스트에 대해 구성할 수 있어요.
참고: 코드 자동 계측(권장 방식)을 사용한다면 계측 코드가 어떤 사용자 코드보다 먼저 실행된다는 점에 유의하세요. 따라서 아래의 환경 변수와 INI 설정은 서버 수준에서 설정되어 어떤 사용자 코드가 실행되기 전에 PHP 런타임에서 사용 가능해야 해요. 예를 들어 putenv()와 .env 파일은 동작하지 않아요.
Apache
PHP-FPM과 함께 Apache를 사용하는 경우 www.conf 구성 파일에서 env[] 지시문을 사용해 PHP 트레이서를 구성하세요. 예:
; 호스트 환경 변수 SOME_ENV를 PHP 프로세스에 DD_AGENT_HOST로 전달하는 예
env[DD_AGENT_HOST] = $SOME_ENV
; 값 'my-app'을 PHP 프로세스에 DD_SERVICE로 전달하는 예
env[DD_SERVICE] = my-app
; 동등한 INI 설정으로 사용하려면
php_value datadog.service my-app
참고: 기본적으로 www.conf에 clear_env=yes가 설정되어 있으면 PHP-FPM은 호스트 시스템의 환경 변수를 상속하지 않아요. 호스트에 설정된 환경 변수를 사용해야 한다면 env[] 지시문으로 명시적으로 정의해야 해요.
PHP-FPM 없는 Apache(mod_php 설정)에서는 서버 구성, 가상 호스트, 디렉터리, .htaccess 파일에서 SetEnv를 사용해 환경 변수를 직접 설정할 수 있어요:
# 가상 호스트 구성에서 환경 변수로
SetEnv DD_TRACE_DEBUG 1
# 가상 호스트 구성에서 INI 설정으로
php_value datadog.service my-app
NGINX 및 PHP-FPM
PHP-FPM은 env[...] 지시문에서 false 값을 지원하지 않아요. true 대신 1, false 대신 0을 사용하세요.
NGINX의 경우 php-fpm의 www.conf 파일에서 env 지시문을 사용하세요. 예:
; 호스트 환경 변수 SOME_ENV를 PHP 프로세스에 DD_AGENT_HOST로 전달하는 예
env[DD_AGENT_HOST] = $SOME_ENV
; 값 'my-app'을 PHP 프로세스에 DD_SERVICE로 전달하는 예
env[DD_SERVICE] = my-app
; 동등한 INI 설정으로 사용하려면
php_value[datadog.service] = my-app
참고: NGINX 서버에 APM을 활성화했다면 분산 트레이싱이 제대로 작동하도록 opentracing_fastcgi_propagate_context 설정을 올바르게 구성했는지 확인하세요. 자세한 내용은 NGINX APM 구성을 참고하세요.
PHP CLI 서버
서버를 시작하는 명령줄에서 설정하세요.
DD_TRACE_DEBUG=1 php -d datadog.service=my-app -S localhost:8888
구성 키 (Configuration keys)
이 라이브러리에 사용 가능한 구성 키는 194개예요.
일반 설정 (General Settings)
(8)
최상위 Datadog 구성: API 키, 서비스 식별, Agent 연결, 인테이크 사이트, 호스트명, 전역 태그, 프록시 설정.
DD_AGENT_HOST
타입: string 기본값: localhost 별칭: DD_TRACE_AGENT_HOSTNAME 트레이스를 위해 Datadog Agent에 연결할 때 사용하는 호스트 이름이에요. 호스트 이름은 IPv4, IPv6, 또는 도메인 이름일 수 있어요. DD_TRACE_AGENT_URL이 지정되면 DD_AGENT_HOST 값은 무시돼요.
DD_APM_TRACING_ENABLED
타입: boolean 기본값: true 별칭: DD_TRACING_ENABLED APM 트레이스 데이터 전송을 활성화하거나 비활성화해요. 비활성화하면 다른 제품을 지원하기 위해 트레이싱은 계속 실행되지만, 주기적인 하트비트 트레이스와 수동으로 유지된 트레이스만 전송돼요.
DD_AUTOLOAD_NO_COMPILE
타입: boolean 기본값: false 이 옵션이 꺼져 있으면 트레이서는 소스 파일을 수동으로 포함하는 대신 효율성을 위해 단일 사전 컴파일 파일(bridge/_generated_*.php)을 포함해요. 컴파일되지 않은 트레이서 소스 파일에 대한 변경 사항을 적용하려면 이 옵션을 활성화하세요.
DD_ENV
타입: string 트레이서가 내보내는 모든 텔레메트리(트레이스, 메트릭, 로그, 프로파일)에 적용되는 전역 env 태그를 설정해요. prod, staging, dev 같은 환경을 구분하는 데 사용해요.
DD_SERVICE
타입: string 애플리케이션의 서비스 이름을 설정해요.
DD_SERVICE_MAPPING
타입: map 각 플러그인에 대한 서비스 이름을 제공해요. 공백 유무와 관계없이 쉼표로 구분된 plugin:service-name 쌍을 받아요.
DD_TAGS
타입: map 쉼표로 구분된 key:value 쌍(예: layer:api,team:intake)으로 제공되는, 트레이스·프로파일·메트릭에 적용되는 사용자 지정 태그예요.
DD_VERSION
타입: string
트레이스와 로그에서 version 태그로 사용되는 애플리케이션 버전을 설정해요(예: 1.2.3, 6c44da20, 2020.02.13).
언어별 참고:
- PHP: 버전
0.90.0부터 런타임에서ini_set('datadog.version', ...)로 변경한 사항이 현재 루트 스팬에도 적용돼요.
트레이싱 코어 (Tracing Core)
(39)
핵심 분산 트레이싱 엔진: Agent 연결, 트레이스·스팬 ID 생성, 스팬 수명주기 관리, 피어 서비스 매핑, 리소스 정규화, 쿼리 문자열 난독화, DB 클라이언트 구성.
DD_AUTOFINISH_SPANS
타입: boolean 기본값: false 트레이서가 플러시될 때 스팬이 자동으로 종료되는지 여부.
DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED
타입: boolean 기본값: true 트레이서가 128비트 W3C 트레이스 ID(32자 hex)를 생성할지, 64비트 Datadog 트레이스 ID(16자 hex)를 생성할지 제어해요. 완전한 W3C traceparent 상호운용성을 위해 128비트 ID가 필요해요.
DD_TRACE_128_BIT_TRACEID_LOGGING_ENABLED
타입: boolean 기본값: true 128비트 트레이스 ID를 전체 32자 형식으로 로깅할지, 아니면 16자로 줄일지 제어해요. 더 짧은 형식을 기대하는 시스템과의 호환성을 위해 false로 설정하세요.
DD_TRACE_AGENT_CONNECT_TIMEOUT
타입: int 기본값: 100 Agent 연결 타임아웃(밀리초).
DD_TRACE_AGENT_PORT
타입: int 기본값: 8126 트레이서가 제출하는 Trace Agent의 포트예요. Agent 구성에서 receiver_port나 DD_APM_RECEIVER_PORT를 기본값 8126이 아닌 값으로 설정했다면 DD_TRACE_AGENT_PORT 또는 DD_TRACE_AGENT_URL이 그 값과 일치해야 해요.
DD_TRACE_AGENT_TIMEOUT
타입: int 기본값: 3000 버전: v1.24.0 Datadog Agent와의 네트워크 상호작용 타임아웃(초).
DD_TRACE_AGENT_URL
타입: string 별칭: DD_TRACE_URL 트레이스가 전송되는 URL 엔드포인트를 설정해요. 설정하면 DD_AGENT_HOST와 DD_TRACE_AGENT_PORT를 재정의해요. 기본값은 http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT>이에요.
DD_TRACE_ANALYTICS_ENABLED
타입: boolean 기본값: false 각 통합의 구성된 애널리틱스 샘플 비율을 사용해 스팬에 analytics.sample_rate 메트릭을 설정함으로써 모든 통합에 대해 레거시 Trace Analytics 기능을 활성화해요. 새 Datadog 배포에서는 App Analytics로 대체돼요.
DD_TRACE_CLIENT_IP_ENABLED
타입: boolean 기본값: false HTTP 요청 헤더에서 클라이언트 IP 주소의 자동 수집을 활성화하거나 비활성화해요. 활성화하면 IP 주소가 http.client_ip 스팬 태그에 저장돼요.
DD_TRACE_CLIENT_IP_HEADER
타입: string http.client_ip 태그 값을 가져올 사용자 지정 헤더 이름을 구성해요. 이 변수가 설정되면 다른 모든 IP 관련 헤더는 무시돼요(예: DD_TRACE_CLIENT_IP_HEADER=custom-ip-header로 설정하고 요청에 custom-ip-header: 5.6.7.9 헤더를 포함하면 "http.client_ip": "5.6.7.9"로 태그된 스팬이 생성돼요). 빈 문자열이나 null 값이 전달되면 IP 헤더는 다음 순서로 조회돼요: - x-forwarded-for - x-real-ip - true-client-ip - x-client-ip - x-forwarded - forwarded-for - x-cluster-client-ip - fastly-client-ip - cf-connecting-ip - cf-connecting-ipv6
DD_TRACE_DB_CLIENT_SPLIT_BY_INSTANCE
타입: boolean 기본값: false HTTP 요청의 서비스 이름을 pdo-로 설정해요. 예를 들어 데이터베이스 호스트 datadoghq.com에 대한 PDO->query() 호출은 기본 서비스 이름 pdo 대신 pdo-datadoghq.com이라는 서비스 이름을 갖게 돼요.
DD_TRACE_ENABLED
타입: boolean 기본값: true 별칭: DD_TRACING_ENABLED 프레임워크 및 라이브러리 계측을 활성화해요. false로 설정하면 애플리케이션 코드가 트레이스를 생성하지 않아요. DD_APM_TRACING_ENABLED도 참고하세요.
DD_TRACE_FORKED_PROCESS
타입: boolean 기본값: true 애플리케이션이 pcntl_unshare(CLONE_NEWUSER);를 호출하고 트레이서가 설치되어 있으면 애플리케이션이 치명적으로 충돌해요. CLONE_NEWUSER가 있는 unshare는 프로세스가 스레드화되지 않아야 하는 반면, PHP 트레이서는 메인 프로세스를 차단하지 않고 Datadog Agent에 트레이스를 보내기 위해 별도의 스레드를 사용하기 때문이에요.
DD_TRACE_GENERATE_ROOT_SPAN
타입: boolean 기본값: true 요청 진입 시 최상위 스팬을 자동으로 생성해요. 오래 실행되는 프로세스를 계측하려면 DD_TRACE_AUTO_FLUSH_ENABLED=1과 함께 0으로 설정하세요.
DD_TRACE_HEALTH_METRICS_ENABLED
타입: boolean 기본값: false true로 설정하면 트레이서 상태 메트릭을 보내요.
DD_TRACE_MEASURE_COMPILE_TIME
타입: boolean 기본값: true 요청의 컴파일 시간(밀리초)을 최상위 스팬에 기록해요.
DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP
타입: string 기본값: (?i)(?:(?:\"|%22)?)(?:(?:old[-_]?|new[-_]?)?p(?:ass)?w(?:or)?d(?:1|2)?|pass(?:[-_]?phrase)?|secret|(?:api[-_]?|private[-_]?|public[-_]?|access[-_]?|secret[-_]?|app(?:lication)?[-_]?)key(?:[-_]?id)?|token|consumer[-_]?(?:id|key|secret)|sign(?:ed|ature)?|auth(?:entication|orization)?)(?:(?:\\s|%20)*(?:=|%3D)[^&]+|(?:\"|%22)(?:\\s|%20)*(?::|%3A)(?:\\s|%20)*(?:\"|%22)(?:%2[^2]|%[^2]|[^\"%])+(?:\"|%22))|(?:bearer(?:\\s|%20)+[a-z0-9._\\-]+|token(?::|%3A)[a-z0-9]{13}|gh[opsu]_[0-9a-zA-Z]{36}|ey[I-L](?:[\\w=-]|%3D)+\\.ey[I-L](?:[\\w=-]|%3D)+(?:\\.(?:[\\w.+/=-]|%3D|%2F|%2B)+)?|-{5}BEGIN(?:[a-z\\s]|%20)+PRIVATE(?:\\s|%20)KEY-{5}[^\\-]+-{5}END(?:[a-z\\s]|%20)+PRIVATE(?:\\s|%20)KEY(?:-{5})?(?:\\n|%0A)?|(?:ssh-(?:rsa|dss)|ecdsa-[a-z0-9]+-[a-z0-9]+)(?:\\s|%20|%09)+(?:[a-z0-9/.+]|%2F|%5C|%2B){100,}(?:=|%3D)*(?:(?:\\s|%20|%09)+[a-z0-9._-]+)?) 들어오는 HTTP 요청의 쿼리 문자열에서 민감한 데이터를 편집하기 위해 정규식을 적용해요. 기본 정규식은 비밀번호, 토큰, API 키, 개인 키, 인증 용어 등 다양한 민감 데이터 패턴을 매칭해요. 매칭된 항목은 <redacted>로 대체돼요. 빈 문자열이 전달되면 난독화가 발생하지 않아요. 결과 값은 http.url 태그에 보고돼요.
DD_TRACE_PEER_SERVICE_DEFAULTS_ENABLED
타입: boolean 기본값: false 활성화하면 트레이서가 Naming Schema v0에서 v1 피어 서비스 기본 알고리즘을 사용해 적격 스팬에 대한 기본 peer.service 값을 계산해요. 비활성화하면 Naming Schema v0는 peer.service를 설정하지 않은 채 둬요.
DD_TRACE_PEER_SERVICE_MAPPING
타입: map 감지된 피어 서비스 이름을 스팬에 부착하기 전에 정규화된 값으로 매핑해요.
DD_TRACE_REMOVE_AUTOINSTRUMENTATION_ORPHANS
타입: boolean 기본값: false 자동 계측으로 생성된 고아 스팬을 자동으로 제거해요. 현재는 Laravel Horizon 맥락에서 사용되는 일부 Redis와 Laravel 호출에만 적용돼요. 버전 0.88.0에 추가됨. 참고: 이러한 고아 스팬은 플러시되지만 트레이스에 기록되지 않아요. 또한 이 구성 옵션으로 제거되는 특정 단일 스팬 트레이스는: - laravel.event.handle
DD_TRACE_REMOVE_INTEGRATION_SERVICE_NAMES_ENABLED
타입: boolean 기본값: false 활성화하면 Naming Schema v0에서 통합이 추론된 서비스 이름 사용을 중지하고 애플리케이션 서비스 이름으로 대체해요. 통합과 무관하게 모든 스팬이 DD_SERVICE 아래에 보고되도록 하려면 이 옵션을 사용하세요.
DD_TRACE_REMOVE_ROOT_SPAN_LARAVEL_QUEUE
타입: boolean 기본값: true 활성화하면 Laravel Queue와 Horizon 명령에 대해 루트 스팬 생성을 자동으로 비활성화하고 자동 플러시를 활성화해요.
DD_TRACE_REMOVE_ROOT_SPAN_SYMFONY_MESSENGER
타입: boolean 기본값: true 활성화하면 Symfony Messenger 명령에 대해 루트 스팬 생성을 자동으로 비활성화하고 자동 플러시를 활성화해요.
DD_TRACE_REPORT_HOSTNAME
타입: boolean 기본값: false 각 트레이스에 대해 시스템 호스트명을 보고할지 여부. 비활성화하면 대신 Agent의 호스트명이 사용돼요.
DD_TRACE_RESOURCE_RENAMING_ALWAYS_SIMPLIFIED_ENDPOINT
타입: boolean 기본값: false 활성화하면 명시적 엔드포인트를 사용할 수 있을 때에도 항상 http.endpoint 태그를 Resource Renaming 단순화 알고리즘의 결과로 설정해요.
DD_TRACE_RESOURCE_RENAMING_ENABLED
타입: boolean 기본값: false 들어오는 HTTP 요청에 대해 http.endpoint 태그를 계산해 추가할지 제어해요. 기본적으로 애플리케이션 보안이 시작 시 활성화되지 않는 한 비활성화되어 있고, 이 설정으로 명시적으로 활성화하거나 비활성화할 수 있어요.
DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX
타입: array ID에 해당하는 경로 조각을 식별하는 정규식의 CSV(리소스 이름을 정규화된 URI로 매핑 참고).
DD_TRACE_RESOURCE_URI_MAPPING_INCOMING
타입: array 들어오는 요청의 리소스 이름을 정규화하기 위한 URI 매핑의 CSV(리소스 이름을 정규화된 URI로 매핑 참고).
DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING
타입: array 나가는 요청의 리소스 이름을 정규화하기 위한 URI 매핑의 CSV(리소스 이름을 정규화된 URI로 매핑 참고).
DD_TRACE_RESOURCE_URI_QUERY_PARAM_ALLOWED
타입: array 리소스 URI의 일부로 수집할 쿼리 매개변수의 쉼표 구분 목록이에요. 매개변수를 수집하지 않으려면 비워 두고, 모든 매개변수를 수집하려면 *로 설정하세요. 버전 0.74.0에서 추가됨.
DD_TRACE_RETAIN_THREAD_CAPABILITIES
타입: boolean 기본값: false Linux에서 동작해요. 유효 사용자 ID를 변경할 때 Datadog 백그라운드 스레드에서 권한(capabilities)을 유지하려면 true로 설정하세요. 이 옵션은 대부분의 설정에 영향을 주지 않지만, 일부 모듈(현재 Datadog이 알고 있는 것은 Apache의 mod-ruid2뿐)이 setuid()나 유사한 syscall을 호출해 권한을 잃게 되어 충돌이나 기능 손실을 초래할 수 있어요. 참고: 이 옵션을 활성화하면 보안이 손상될 수 있어요. 이 옵션은 단독으로는 보안 위험을 초래하지 않아요. 그러나 웹 서버나 PHP가 전체 권한으로 시작되었다면 백그라운드 스레드가 원래 권한을 유지하므로, PHP나 웹 서버의 취약점을 악용할 수 있는 공격자가 비교적 쉽게 권한을 상승시킬 수 있어요. Datadog은 setcap 유틸리티로 웹 서버의 권한을 제한할 것을 권장해요.
DD_TRACE_SECURE_RANDOM
타입: boolean 기본값: false 버전: v1.20.0 보안 난수 ID 생성: 활성화하면 트레이서가 트레이스/스팬 ID에 SECURE_RANDOM ID 생성 전략(SecureRandom 기반)을 사용하도록 강제해요. AWS Lambda SnapStart(AWS_LAMBDA_INITIALIZATION_TYPE=snap-start)에서도 강제로 적용돼요. 기본값: false.
DD_TRACE_SIDECAR_BACKPRESSURE_BYTES
타입: int 기본값: 4194304 사이드카 채널의 데이터가 버려지기 시작하기 전 버퍼링되는 최대 바이트 수.
DD_TRACE_SIDECAR_BACKPRESSURE_QUEUE
타입: int 기본값: 100 메시지가 버려지기 전 사이드카가 수신할 수 있는 처리되지 않은 최대 메시지 수.
DD_TRACE_SIDECAR_CONNECTION_MODE
타입: string 기본값: auto
사이드카 연결 모드를 결정해요:
- subprocess: 같은 사용자로 실행되는 다른 많은 프로세스가 접근할 수 있는 하위 프로세스를 생성해요.
- thread: 사이드카를 스레드 모드로 실행하며 포크에서만 접근할 수 있어요.
DD_TRACE_SIDECAR_TRACE_SENDER
타입: boolean 기본값: false 트레이스를 백그라운드 발신자로 보낼지 사이드카로 보낼지 결정해요. Windows에서는 강제로 활성화돼요. 이 구성은 향후 폐기될 예정이며 백그라운드 발신자는 제거될 거예요.
DD_TRACE_SPANS_LIMIT
타입: int 기본값: 1000 하나의 트레이스 내에서 생성되는 최대 스팬 수예요. 최대 스팬 수에 도달하면 더 이상 스팬이 생성되지 않아요. 한도를 늘리면 보류 중인 트레이스가 사용하는 메모리 양이 증가해 PHP 최대 허용 메모리 한도에 도달할 수 있어요. 최대 허용 메모리 양은 PHP INI 시스템 설정 memory_limit으로 늘릴 수 있어요.
DD_TRACE_STATS_COMPUTATION_ENABLED
타입: boolean 기본값: false 버전: v1.19.0 stats 페이로드 생성과 수집 측 메트릭을 위해 트레이서에서 트레이스 통계 계산을 활성화해요.
DD_TRACE_X_DATADOG_TAGS_MAX_LENGTH
타입: int 기본값: 512 트레이스 태그 전파를 위한 x-datadog-tags 헤더의 최대 길이예요. 비활성화하려면 0으로 설정하세요.
트레이스 샘플링 (Trace Sampling)
(7)
어떤 트레이스와 스팬을 유지하거나 버릴지 결정하는 샘플링 규칙과 비율. 서비스별 규칙, 비율 제한, 우선순위 샘플링을 포함해요.
DD_SPAN_SAMPLING_RULES
타입: array 기본값: [] 나머지 트레이스가 버려질 때 개별 스팬을 유지하기 위한 스팬 샘플링 규칙이에요. 객체의 JSON 배열이에요. 규칙은 구성된 순서대로 적용되어 스팬의 샘플 비율을 결정해요. sample_rate 값은 0.0~1.0(포함) 사이여야 해요. 자세한 내용은 수집 메커니즘을 참고하세요. 예: 서비스 my-service와 운영 이름 http.request에 대해 스팬 샘플 비율을 50%, 최대 초당 50 트레이스로 설정: [{"service": "my-service", "name": "http.request", "sample_rate":0.5, "max_per_second": 50}].
DD_SPAN_SAMPLING_RULES_FILE
타입: string 스팬 샘플링 규칙이 포함된 JSON 파일을 가리켜요. DD_SPAN_SAMPLING_RULES가 이 변수보다 우선해요. 규칙 형식은 DD_SPAN_SAMPLING_RULES를 참고하세요.
DD_TRACE_RATE_LIMIT
타입: int 기본값: 100 초당 샘플링할 최대 트레이스 수를 설정해요. DD_TRACE_SAMPLING_RULES 또는 DD_TRACE_SAMPLE_RATE 중 하나가 설정된 경우에만 적용돼요.
DD_TRACE_SAMPLE_RATE
타입: decimal 기본값: -1 Agent와 백엔드 사이의 수집 샘플 비율(0.0~1.0)을 제어해요.
DD_TRACE_SAMPLING_RULES
타입: array 기본값: []
트레이스 수집을 세밀하게 제어할 수 있게 해 주며, 특정 서비스·운영·리소스·태그 트레이스를 대상으로 삼을 수 있어요. 각 객체가 0.0~1.0(포함) 사이의 sample_rate를 포함해야 하는 JSON 배열로 정의돼요. 선택적으로 service, name, resource, tags, max_per_second 필드를 포함할 수 있어요. 객체는 나열된 순서대로 평가되며, 첫 번째 일치하는 객체가 트레이스의 샘플 비율을 결정해요. 자세한 내용은 수집 메커니즘을 참고하세요.
예시:
- 모든 트레이스의 20% 샘플링:
[{"sample_rate": 0.2}] - 서비스 이름이
a로 시작하고 운영 이름이b인 트레이스의 10%, 나머지의 20% 샘플링:[{"service": "a.*", "name": "b", "sample_rate": 0.1}, {"sample_rate": 0.2}] - 리소스 이름
HTTP GET트레이스의 40% 샘플링:[{"resource": "HTTP GET", "sample_rate": 0.4}] - 태그
tier=premium트레이스의 100% 샘플링:[{"tags": {"tier": "premium"}, "sample_rate": 1}] - 서비스
my-service와 운영 이름http.request에 대해 50% 비율로 초당 최대 50 트레이스 샘플링:[{"service": "my-service", "name": "http.request", "sample_rate": 0.5, "max_per_second": 50}]
DD_TRACE_SAMPLING_RULES_FORMAT
타입: string 기본값: glob 사용자 지정 샘플링 규칙의 형식을 설정해요. 유효한 값은 regex 또는 glob이에요. 값이 인식되지 않으면 트레이스 샘플링 규칙이 비활성화돼요.
DD_TRACE_WEBSOCKET_MESSAGES_INHERIT_SAMPLING
타입: boolean 기본값: true 기본적으로 websocket 메시지는 핸드셰이크 중 캡처된 스팬과 동일한 샘플링을 유지해요. 이는 핸드셰이크 스팬이 샘플링되었다면 해당 세션의 모든 메시지도 샘플링되도록 보장해요. 이 동작을 비활성화하고 각 websocket 메시지를 독립적으로 샘플링하려면 false로 설정하세요.
트레이스 전파 (Trace Propagation)
(18)
분산 트레이스 컨텍스트 전파, 추출·주입 동작, 배기지(baggage) 처리, 헤더 태깅, HTTP 클라이언트·서버 구성, Database Monitoring을 위한 SQL 주석 주입.
DD_DBM_ALWAYS_APPEND_SQL_COMMENT
타입: boolean 기본값: false 버전: v1.21.0 DD_DBM_PROPAGATION_MODE가 설정되면 SQL 쿼리에 주석이 주입돼요. 대부분의 경우 앞에 붙어요. 이 구성은 주석이 항상 뒤에 붙도록 강제해요.
DD_DISTRIBUTED_TRACING
타입: boolean 기본값: true 분산 트레이싱을 활성화할지 여부.
DD_EXPERIMENTAL_PROPAGATE_PROCESS_TAGS_ENABLED
타입: boolean 기본값: true 프로세스 수준 태그(예: 진입점 메타데이터)가 수집되어 트레이싱 페이로드에 부착되는지 제어해요.
DD_HTTP_SERVER_ROUTE_BASED_NAMING
타입: boolean 기본값: true false로 설정하면 HTTP 프레임워크 라우트가 리소스 이름에 사용되지 않아요. 변경하면 리소스 이름과 파생 메트릭이 바뀔 수 있어요.
DD_TRACE_BAGGAGE_MAX_BYTES
타입: int 기본값: 8192 다운스트림 서비스로 전파할 때 baggage 헤더에 주입할 수 있는 최대 바이트 수를 설정하는 구성 키예요. 기본값은 8192바이트예요.
DD_TRACE_BAGGAGE_MAX_ITEMS
타입: int 기본값: 64 다운스트림 서비스로 전파할 때 baggage 헤더에 주입할 수 있는 최대 항목 수를 설정하는 구성 키예요. 기본값은 64개 항목이에요.
DD_TRACE_BAGGAGE_TAG_KEYS
타입: array 기본값: user.id, session.id, account.id 스팬 태그에 복사할 baggage 키의 쉼표 구분 목록이에요. 모든 baggage 항목에 태그를 붙이려면 *로 설정하고, 설정하지 않으면 기본 허용 목록이 사용돼요.
DD_TRACE_HEADER_TAGS
타입: map 지정된 HTTP 헤더를 스팬 태그로 자동 적용해요. 사용자 지정 태그 이름이 지정되지 않으면 태그 키는 요청 헤더의 경우 http.request.headers.로, 응답 헤더의 경우 http.response.headers.로 기본 설정돼요.
DD_TRACE_HTTP_CLIENT_ERROR_STATUSES
타입: array 기본값: 400-499 HTTP 클라이언트 스팬에서 오류로 처리할 HTTP 상태 코드와 범위의 쉼표 구분 목록이에요(예: 400-499,500). 설정하면 일치하는 응답이 스팬을 오류로 표시해요.
DD_TRACE_HTTP_CLIENT_SPLIT_BY_DOMAIN
타입: boolean 기본값: false HTTP 요청의 서비스 이름을 host-로 설정해요. 예를 들어 https://datadoghq.com에 대한 curl_exec() 호출은 기본 서비스 이름 curl 대신 host-datadoghq.com이라는 서비스 이름을 갖게 돼요.
DD_TRACE_HTTP_POST_DATA_PARAM_ALLOWED
타입: array 스팬 태그로 수집할 HTTP POST 데이터 필드의 쉼표 구분 목록이에요. 모든 필드를 수집하려면 *를 사용하세요. DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP와 일치하는 값은 편집돼요. 아무것도 수집하지 않으려면 비워 두세요.
DD_TRACE_HTTP_SERVER_ERROR_STATUSES
타입: array 기본값: 500-599 HTTP 서버 스팬에서 오류로 처리할 HTTP 상태 코드 또는 범위의 쉼표 구분 목록이에요(예: 500-599,404). 5xx 응답만을 오류로 표시하는 기본 동작을 재정의해요.
DD_TRACE_HTTP_URL_QUERY_PARAM_ALLOWED
타입: array 기본값: * URL의 일부로 수집할 쿼리 매개변수의 쉼표 구분 목록이에요. 매개변수를 수집하지 않으려면 비워 두고, 모든 매개변수를 수집하려면 *로 설정하세요. 버전 0.74.0에서 추가됨.
DD_TRACE_INFERRED_PROXY_SERVICES_ENABLED
타입: boolean 기본값: false 별칭: DD_TRACE_INFERRED_SPANS_ENABLED 활성화하면 트레이서가 추론 프록시 프로파게이터를 등록하는데, 이는 x-dd-proxy* 헤더(현재 x-dd-proxy=aws-apigateway)를 읽고 서버 스팬의 부모로 추론 프록시 스팬을 시작하며 서비스·리소스·태그에 헤더 값을 사용해요.
DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT
타입: string 기본값: continue 버전: v1.24.0 들어오는 분산 트레이싱 헤더가 서비스 수준에서 처리되는 방식을 지정해요. 허용 값: continue: 들어오는 분산 트레이싱 헤더가 유효한 트레이스 컨텍스트를 나타내면 SDK가 분산 트레이스를 계속해요. restart: SDK가 항상 새 트레이스를 시작해요. 들어오는 분산 트레이싱 헤더가 유효한 트레이스 컨텍스트를 나타내면 그 트레이스 컨텍스트는 서비스 진입 스팬의 스팬 링크로 표시돼요(continue 구성의 부모 스팬 대신). ignore: SDK가 항상 새 트레이스를 시작하고 모든 들어오는 분산 트레이싱 헤더를 무시해요.
DD_TRACE_PROPAGATION_STYLE
타입: array 기본값: datadog,tracecontext,baggage 별칭: OTEL_PROPAGATORS 분산 트레이싱 전파 데이터를 주입·추출하려 시도할 헤더 형식의 쉼표 구분 목록이에요. 완전하고 유효한 헤더가 있는 첫 번째 형식이 계속할 트레이스를 정의하는 데 사용돼요. 더 구체적인 DD_TRACE_PROPAGATION_STYLE_INJECT, DD_TRACE_PROPAGATION_STYLE_EXTRACT 구성이 있으면 우선해요.
DD_TRACE_PROPAGATION_STYLE_EXTRACT
타입: array 기본값: datadog,tracecontext,B3,B3 single header,baggage 분산 트레이싱 전파 데이터를 추출하려 시도할 헤더 형식의 쉼표 구분 목록이에요. 완전하고 유효한 헤더가 있는 첫 번째 형식이 계속할 트레이스를 정의하는 데 사용돼요.
DD_TRACE_PROPAGATION_STYLE_INJECT
타입: array 기본값: datadog,tracecontext,baggage 별칭: DD_PROPAGATION_STYLE_INJECT, DD_TRACE_PROPAGATION_STYLE 서비스 간 분산 트레이스를 전파하기 위해 포함할 헤더 형식의 쉼표 구분 목록이에요. 완전하고 유효한 헤더가 있는 첫 번째 형식이 계속할 트레이스를 정의하는 데 사용돼요.
트레이스 통합 (Trace Integrations)
(32)
통합별 트레이스 구성: 활성화/비활성화, 애널리틱스, 서비스 이름, 라이브러리 통합에 대한 피어 서비스 재정의, 특정 계측 비활성화 제어.
일반 통합 설정 (General Integration Settings)
DD_TRACE_LARAVEL_QUEUE_DISTRIBUTED_TRACING
타입: boolean 기본값: true 추가 laravel.queue.process 스팬의 생성을 비활성화하고 스팬 링크에만 의존해요. 버전 0.93.0에서 추가됨.
DD_TRACE_SYMFONY_MESSENGER_DISTRIBUTED_TRACING
타입: boolean 기본값: true 비활성화하면 인과적인 생산/소비 관계가 스팬 링크를 사용해 연결돼요. 버전 1.3.0에서 추가됨.
DD_TRACE_SYMFONY_MESSENGER_MIDDLEWARES
타입: boolean 기본값: false Symfony Messenger 미들웨어의 트레이싱을 활성화해요. 버전 1.3.0에서 추가됨.
구성 종류 (Configuration Kinds)
각 통합은 이러한 구성 패턴 중 하나 이상을 지원할 수 있어요. <INTEGRATION>을 통합 이름(예: GRPC, AWS, REDIS)으로 바꾸세요.
DD_TRACE_<INTEGRATION>_ENABLED
(12개 통합)
특정 통합의 트레이싱을 활성화하거나 비활성화해요.
사용 가능한 통합: AMQP, AUTO_FLUSH, CLI, ELASTICSEARCH, KAFKA, MEMCACHED, MONGO, MONGODB, OPENAI, STRIPE, URL_AS_RESOURCE_NAMES, WEBSOCKET_MESSAGES
DD_TRACE_<INTEGRATION>_ANALYTICS_SAMPLE_RATE
(5개 통합)
이 통합의 App Analytics 샘플 비율을 설정해요(0.0~1.0).
사용 가능한 통합: AMQP, ELASTICSEARCH, KAFKA, MONGO, STRIPE
통합별 설정 (Per-Integration Settings) (14개 통합)
각 섹션은 특정 통합에 사용 가능한 모든 구성 키를 나열해요.
AMQP
(3)
DD_TRACE_AMQP_ANALYTICS_ENABLED
타입: boolean 기본값: false 별칭: DD_AMQP_ANALYTICS_ENABLED RabbitMQ AMQP 계측(publish/consume 및 Channel 명령 스팬)이 생성하는 스팬에 대한 트레이스 애널리틱스를 활성화해요.
DD_TRACE_AMQP_ANALYTICS_SAMPLE_RATE
타입: decimal 기본값: 1.0 별칭: DD_AMQP_ANALYTICS_SAMPLE_RATE RabbitMQ AMQP 스팬이 생성하는 애널리틱스 이벤트의 샘플 비율.
DD_TRACE_AMQP_ENABLED
타입: boolean 기본값: true 별칭: DD_INTEGRATION_AMQP_ENABLED, DD_TRACE_INTEGRATION_AMQP_ENABLED RabbitMQ AMQP 클라이언트 계측을 활성화해요(Channel 명령과 메시지 publish/consume에 스팬을 생성하고, AMQP 헤더를 통해 트레이스 컨텍스트를 전파해요).
AUTO_FLUSH
(1)
DD_TRACE_AUTO_FLUSH_ENABLED
타입: boolean 기본값: false 모든 스팬이 닫힐 때 트레이스를 Datadog Agent로 자동 플러시해요. 오래 실행되는 프로세스를 계측하려면 DD_TRACE_GENERATE_ROOT_SPAN=0과 함께 true로 설정하세요.
CLI
(1)
DD_TRACE_CLI_ENABLED
타입: boolean 기본값: true CLI에서 PHP 스크립트의 트레이싱을 활성화해요. CLI 스크립트 트레이싱 문서를 참고하세요.
ELASTICSEARCH
(2)
DD_TRACE_ELASTICSEARCH_ANALYTICS_SAMPLE_RATE
타입: decimal 기본값: 1.0 별칭: DD_ELASTICSEARCH_ANALYTICS_SAMPLE_RATE Elasticsearch 통합이 생성하는 애널리틱스 이벤트의 샘플 비율.
DD_TRACE_ELASTICSEARCH_ENABLED
타입: boolean 기본값: true elasticsearch에 대한 계측을 활성화해요. 비활성화하면 elasticsearch 연산에 대한 스팬이 생성되지 않아요.
KAFKA
(2)
DD_TRACE_KAFKA_ANALYTICS_SAMPLE_RATE
타입: decimal 기본값: 1.0 별칭: DD_KAFKA_ANALYTICS_SAMPLE_RATE Kafka 통합이 생성하는 애널리틱스 이벤트의 샘플 비율.
DD_TRACE_KAFKA_ENABLED
타입: boolean 기본값: true 별칭: DD_INTEGRATION_KAFKA_ENABLED, DD_TRACE_INTEGRATION_KAFKA_ENABLED Kafka 통합의 트레이싱을 활성화해요.
MEMCACHED
(1)
DD_TRACE_MEMCACHED_ENABLED
타입: boolean 기본값: true memcached에 대한 계측을 활성화해요. 비활성화하면 memcached 연산에 대한 스팬이 생성되지 않아요.
MONGO
(2)
DD_TRACE_MONGO_ANALYTICS_SAMPLE_RATE
타입: decimal 기본값: 1.0 별칭: DD_MONGO_ANALYTICS_SAMPLE_RATE MongoDB 통합이 생성하는 애널리틱스 이벤트의 샘플 비율.
DD_TRACE_MONGO_ENABLED
타입: boolean 기본값: true 별칭: DD_INTEGRATION_MONGO_ENABLED, DD_TRACE_INTEGRATION_MONGO_ENABLED MongoDB 통합의 트레이싱을 활성화해요.
MONGODB
(1)
DD_TRACE_MONGODB_ENABLED
타입: boolean 기본값: true mongodb에 대한 계측을 활성화해요. 비활성화하면 mongodb 연산에 대한 스팬이 생성되지 않아요.
OPENAI
(7)
DD_OPENAI_LOG_PROMPT_COMPLETION_SAMPLE_RATE
타입: decimal 기본값: 0.1 프롬프트와 완료를 로그로 수집하는 샘플 비율을 구성해요.
DD_OPENAI_LOGS_ENABLED
타입: boolean 기본값: false 프롬프트와 완료를 로그로 수집하는 것을 활성화해요. 아래에 설명된 샘플 비율 구성으로 수집되는 프롬프트와 완료의 비율을 조정할 수 있어요.
DD_OPENAI_METRICS_ENABLED
타입: boolean 기본값: true OpenAI 메트릭 수집을 활성화해요.
DD_OPENAI_SERVICE
타입: string 별칭: DD_OPENAI_SERVICE_NAME OpenAI 요청에 기본적으로 보고되는 서비스 이름.
DD_OPENAI_SPAN_CHAR_LIMIT
타입: int 기본값: 128 스팬 태그 내 다음 데이터에 대한 최대 문자 수를 구성해요:
DD_OPENAI_SPAN_PROMPT_COMPLETION_SAMPLE_RATE
타입: decimal 기본값: 1.0 프롬프트와 완료를 스팬 태그로 수집하는 샘플 비율을 구성해요.
DD_TRACE_OPENAI_ENABLED
타입: boolean 기본값: true openai에 대한 계측을 활성화해요. 비활성화하면 openai 연산에 대한 스팬이 생성되지 않아요.
REDIS_CLIENT
(1)
DD_TRACE_REDIS_CLIENT_SPLIT_BY_HOST
타입: boolean 기본값: false Redis 클라이언트 연산의 서비스 이름을 redis-로 설정해요.
STRIPE
(3)
DD_TRACE_STRIPE_ANALYTICS_ENABLED
타입: boolean 기본값: false 버전: v1.17.1 별칭: DD_STRIPE_ANALYTICS_ENABLED Stripe 통합에 대한 애널리틱스를 활성화해요.
DD_TRACE_STRIPE_ANALYTICS_SAMPLE_RATE
타입: decimal 기본값: 1.0 버전: v1.17.1 별칭: DD_STRIPE_ANALYTICS_SAMPLE_RATE Stripe 통합이 생성하는 애널리틱스 이벤트의 샘플 비율.
DD_TRACE_STRIPE_ENABLED
타입: boolean 기본값: true 버전: v1.17.1 Stripe 통합의 트레이싱을 활성화해요.
URL_AS_RESOURCE_NAMES
(1)
DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED
타입: boolean 기본값: true URL을 리소스 이름으로 사용하는 것을 활성화해요(리소스 이름을 정규화된 URI로 매핑 참고).
WEBSOCKET_MESSAGES
(2)
DD_TRACE_WEBSOCKET_MESSAGES_ENABLED
타입: boolean 기본값: true 보내고 받은 websocket 메시지(텍스트와 바이너리)와 연결 닫기 이벤트의 트레이싱을 활성화해요.
DD_TRACE_WEBSOCKET_MESSAGES_SEPARATE_TRACES
타입: boolean 기본값: true 기본적으로 각 수신 메시지는 새 트레이스를 생성해요. 핸드셰이크는 스팬 링크로 그 트레이스에 연결돼요. 이 매개변수를 false로 설정하면 세션 중 캡처된 모든 스팬이 같은 트레이스에 있게 돼요.
WORDPRESS
(2)
DD_TRACE_WORDPRESS_ADDITIONAL_ACTIONS
타입: array 계측할 추가 WordPress action 훅의 쉼표 구분 목록이에요. DD_TRACE_WORDPRESS_ENHANCED_INTEGRATION이 활성화된 경우에만 적용돼요.
DD_TRACE_WORDPRESS_CALLBACKS
타입: boolean 기본값: true WordPress action 훅 콜백의 계측을 활성화해요. DD_TRACE_WORDPRESS_ENHANCED_INTEGRATION이 활성화된 경우에만 적용돼요.
Database Monitoring
(2)
DBM(Database Monitoring): SQL 주석 전파 모드와 데이터베이스 성능을 애플리케이션 트레이스와 상관시키기 위한 쿼리 식별자 해싱.
DD_DBM_INJECT_SQL_BASEHASH
타입: boolean 기본값: false DBM 전파도 활성화된 경우 SQL 쿼리에 "기본 해시(base hash)"의 주입을 활성화해요. 이 기본 해시는 일치하는 스팬을 찾고 관련 값으로 쿼리를 보강하는 데 사용돼요.
DD_DBM_PROPAGATION_MODE
타입: string 기본값: disabled service 또는 full로 설정하면 APM에서 보낸 데이터와 Database Monitoring 제품 간의 연결을 활성화해요. service 옵션은 DBM과 APM 서비스 간의 연결을 가능하게 해요. full 옵션은 데이터베이스 스팬과 데이터베이스 쿼리 이벤트 간의 연결을 가능하게 해요. Postgres와 MySQL에서 사용 가능해요.
트레이스 로깅 (Trace Logging)
(4)
트레이서 로그 출력 설정: 로그 수준, 로그 파일 경로, 로그 회전, 시작 진단.
DD_TRACE_DEBUG
타입: boolean 기본값: false 별칭: OTEL_LOG_LEVEL
SDK의 디버그 모드를 활성화해요. 설정하면 SDK가 문제 해결을 위해 자세한 로그 메시지를 내보내요. 활성화되면 DD_TRACE_LOG_LEVEL보다 우선해요. OTEL_LOG_LEVEL을 별칭으로 사용하세요.
언어별 참고:
- PHP: 로그 메시지는 PHP
error_logINI 설정에 지정된 장치나 파일에 기록돼요. 실제 값은 PHP-FPM/Apache 구성 파일에서 재정의될 수 있어php -i출력과 다를 수 있어요.
DD_TRACE_LOG_FILE
타입: string 로그 파일을 지정해요. 지정하지 않으면 로그는 기본 PHP 오류 위치로 이동해요. datadog-ipc-helper 문제(예: 텔레메트리 제출)를 디버깅하려면 로그 파일을 지정해야 해요.
DD_TRACE_LOG_LEVEL
타입: string 기본값: error 디버그 로깅이 활성화될 때 트레이서가 사용할 최소 로그 수준의 문자열이에요(예: error, debug).
DD_TRACE_STARTUP_LOGS
타입: boolean 기본값: true 트레이서가 초기화될 때 시작 구성과 진단 로그 줄의 생성을 활성화해요.
지속적 프로파일링 (Continuous Profiling)
(12)
Continuous Profiler 구성: 활성화/비활성화, 업로드 설정, 프로파일링 유형, 엔진 옵션, 코드 핫스팟, 엔드포인트 프로파일링, 실험 기능.
DD_PROFILING_ALLOCATION_ENABLED
타입: boolean 기본값: true 별칭: DD_PROFILING_DDPROF_ALLOC_ENABLED true로 설정하면 할당 프로파일링(Preview)을 활성화해요.
DD_PROFILING_ALLOCATION_SAMPLING_DISTANCE
타입: int 기본값: 4194304 할당 샘플 사이의 평균 할당 바이트 수. 낮을수록 할당 핫스팟 정밀도가 좋아지지만 프로파일러 오버헤드가 증가해요.
DD_PROFILING_ENABLED
타입: boolean 기본값: true 프로파일링을 활성화할지 여부.
DD_PROFILING_ENDPOINT_COLLECTION_ENABLED
타입: boolean 기본값: true 별칭: DD_PROFILING_EXPERIMENTAL_ENDPOINT_COLLECTION_ENABLED 스팬이 최상위 요청 엔드포인트가 포함된 pprof 레이블을 추가해 Datadog UI에서 프로파일을 엔드포인트별로 그룹화할 수 있게 할지 제어해요.
DD_PROFILING_EXCEPTION_ENABLED
타입: boolean 기본값: true 예외 이벤트 프로파일링을 활성화해 예외가 많은 코드 경로가 프로파일에 나타나게 해요. 오류 폭풍이나 예외를 통한 제어 흐름을 진단할 때 유용해요.
DD_PROFILING_EXCEPTION_MESSAGE_ENABLED
타입: boolean 기본값: false 수집된 예외 샘플에 예외 메시지 텍스트를 포함해요. 메시지 내용이 디버깅에 필요하고 데이터 민감성 정책에서 허용될 때만 활성화하세요.
DD_PROFILING_EXCEPTION_SAMPLING_DISTANCE
타입: int 기본값: 100 예외 프로파일링 이벤트의 샘플링 간격. 낮을수록 더 많은 예외 세부 정보를 캡처하고, 높을수록 오버헤드를 줄여요.
DD_PROFILING_EXPERIMENTAL_CPU_TIME_ENABLED
타입: boolean 기본값: true 별칭: DD_PROFILING_EXPERIMENTAL_CPU_ENABLED 벽시계 시간 외에 CPU 시간 샘플 차원을 수집해요. 실제 CPU 포화를 대기/차단 동작과 구분해야 할 때 사용하세요.
DD_PROFILING_EXPERIMENTAL_FEATURES_ENABLED
타입: boolean 기본값: false 실험적 프로파일링 기능을 활성화하는 포괄 스위치. 평가/조기 채택을 위한 것이므로 광범위한 배포 전에 오버헤드와 정확성을 검증하세요.
DD_PROFILING_EXPERIMENTAL_IO_ENABLED
타입: boolean 기본값: false 저수준 파일/소켓 I/O 연산을 계측해 프로파일이 (단지 CPU가 아닌) 읽기/쓰기 활동에 시간을 귀속시킬 수 있게 해요. 디스크/네트워크 대기 또는 외부 호출의 알 수 없는 차단이 지배하는 지연을 조사할 때 사용하세요.
DD_PROFILING_LOG_LEVEL
타입: string 기본값: off 프로파일러 로그 수준을 설정해요. 허용 값: off, error, warn, info, debug, trace. 프로파일러 로그는 프로세스의 표준 오류 스트림에 기록돼요.
DD_PROFILING_TIMELINE_ENABLED
타입: boolean 기본값: true 별칭: DD_PROFILING_EXPERIMENTAL_TIMELINE_ENABLED
타임라인 프로파일 유형을 활성화해요.
참고: 이 변수는 DD_PROFILING_EXPERIMENTAL_TIMELINE_ENABLED 환경 변수(datadog.profiling.experimental_timeline_enabled INI 설정)를 대체해요. 둘 다 설정되면 이 변수가 우선해요.
언어별 참고:
- PHP: 이 변수는
0.89부터 사용 가능한datadog.profiling.experimental_timeline_enabledINI 설정을 대체해요.
애플리케이션 보안 (Application Security)
(23)
Application Security 구성: ASM 위협 감지와 차단, 사용자 이벤트 추적, IAST 취약점 감지, API Security 스키마 발견, 오류 추적.
DD_API_SECURITY_ENABLED
타입: boolean 기본값: true 별칭: DD_EXPERIMENTAL_API_SECURITY_ENABLED API Security 기능이 활성화되는지 제어해요. 설정하지 않으면 API Security는 기본적으로 활성화돼요.
DD_APPSEC_AGENTIC_ONBOARDING
타입: string 버전: v1.24.0 Datadog의 에이전트형(agentic) 온보딩 솔루션이 서비스에 App & API Protection을 구성할 때 자동으로 설정하는 정식 Datadog 환경 변수예요. 계측 텔레메트리를 통해 서비스가 에이전트형 플로우로 온보딩되었음을 Datadog이 기록할 수 있게 해 줘요.
DD_APPSEC_AUTO_USER_INSTRUMENTATION_MODE
타입: string 기본값: ident 별칭: DD_APPSEC_AUTOMATED_USER_EVENTS_TRACKING 자동 사용자 이벤트에 사용할 수집 모드를 지정해요.
DD_APPSEC_AUTOMATED_USER_EVENTS_TRACKING_ENABLED
타입: boolean 기본값: true AppSec 사용자 수명주기 신호(로그인 성공/실패, 가입, 인증된 사용자)의 자동 방출을 스팬 메타데이터로 활성화해요. SDK 이벤트를 수동으로 방출하지 않고 계정 남용·인증 관련 감지를 원할 때 사용하세요.
DD_APPSEC_CLI_START_ON_RINIT
타입: boolean 기본값: false
CLI와 FrankenPHP SAPI에서 PHP RINIT 동안 AppSec 요청 수명주기 시작을 강제해요.
AppSec은 HTTP 요청의 시작과 끝을 추적해요. CLI와 FrankenPHP의 PHP "요청" 초기화는 일반적으로 요청의 시작에 해당하지 않아요. 그러나 FrankenPHP를 클래식 모드(워커 모드가 아닌)로 실행한다면 이 가정은 성립하지 않으므로 DD_APPSEC_CLI_START_ON_RINIT을 true로 설정해야 해요.
DD_APPSEC_ENABLED
타입: boolean 기본값: false 트레이서 내부에서 AppSec 제품을 활성화하거나 비활성화해요. 활성화하면 트레이서가 AppSec 모듈(인앱 WAF, 헤더/본문 수집, AppSec 텔레메트리)을 초기화해요.
DD_APPSEC_EXTRA_HEADERS
타입: array 기본 제공 관련 헤더 집합 외에 AppSec이 수집·분석할 추가 HTTP 헤더 이름을 추가해요. 환경이 사용자 지정 헤더(게이트웨이 ID, 테넌트 ID, 전달된 인증 컨텍스트 등)에 보안 관련 컨텍스트를 실을 때 사용하세요.
DD_APPSEC_HTTP_BLOCKED_TEMPLATE_HTML
타입: string 요청이 차단되고 응답이 HTML이어야 할 때 반환할 로컬 HTML 템플릿 파일 경로. 설정되지 않았거나 유효하지 않으면 트레이서는 제품 RFC가 정의한 기본 차단 HTML 템플릿을 사용해요. 트레이서는 Accept 헤더 또는 차단 액션의 매개변수에 따라 HTML 또는 JSON을 결정해요.
DD_APPSEC_HTTP_BLOCKED_TEMPLATE_JSON
타입: string 요청이 차단되고 응답이 JSON이어야 할 때 반환할 로컬 JSON 템플릿 파일 경로. 설정되지 않았거나 유효하지 않으면 트레이서는 제품 RFC가 정의한 기본 차단 JSON 템플릿을 사용해요. 트레이서는 Accept 헤더 또는 차단 액션의 매개변수에 따라 HTML 또는 JSON을 선택해요.
DD_APPSEC_LOG_FILE
타입: string 기본값: php_error_reporting AppSec 확장 로그의 대상을 선택해요(php_error_reporting, syslog, stdout, stderr, 또는 파일 경로).
DD_APPSEC_LOG_LEVEL
타입: string 기본값: warn AppSec 확장 로그 상세도를 제어해요(off, fatal, error, warning/warn, info, debug, trace).
DD_APPSEC_MAX_BODY_BUFF_SIZE
타입: int 기본값: 524288 AppSec 검사를 위해 버퍼링할 요청/응답 본문의 최대 바이트 수를 제한해요. 감지에 더 큰 페이로드 가시성이 필요하면 늘리고, 메모리/복사 오버헤드를 줄이려면 낮추세요.
DD_APPSEC_MAX_STACK_TRACE_DEPTH
타입: int 기본값: 32 별칭: DD_APPSEC_MAX_STACKTRACE_DEPTH AppSec 이벤트에 첨부된 스택 트레이스에 유지되는 최대 스택 프레임 수. 한도에 도달하면 더 깊은 프레임은 잘리고 스택 상단의 프레임은 보존돼요. 이벤트 페이로드 크기를 줄이려면 값을 낮추세요.
DD_APPSEC_MAX_STACK_TRACES
타입: int 기본값: 2 별칭: DD_APPSEC_MAX_STACKTRACES 페이로드 크기를 합리적으로 유지하기 위해 AppSec/IAST 이벤트에 캡처·첨부되는 별도 스택트레이스 수를 제한해요. 증거 스택트레이스는 트라이지에 유용하지만, 무제한 캡처는 민감한 데이터를 유출하고 과도한 대역폭을 소비할 수 있어요. 이 한도는 증거 가치와 안전성 사이의 균형을 유지해요. 모두 수집하려면 0으로 설정하세요.
DD_APPSEC_OBFUSCATION_PARAMETER_KEY_REGEXP
타입: string 기본값: (?i)pass|pw(?:or)?d|secret|(?:api|private|public|access)[_-]?key|token|consumer[_-]?(?:id|key|secret)|sign(?:ed|ature)|bearer|authorization|jsessionid|phpsessid|asp\\.net[_-]sessionid|sid|jwt AppSec 난독화기가 전체 값이 편집되어야 하는 매개변수 키를 식별하는 데 사용하는 정규식이에요. 키 경로가 일치하면 매개변수가 <redacted by datadog>로 대체돼요. 기본값은 일반적인 자격 증명 이름(비밀번호, 토큰, authorization, jwt 등)과 일치해요. 키 기반 편집을 비활성화하려면 빈 문자열로 설정하세요.
DD_APPSEC_OBFUSCATION_PARAMETER_VALUE_REGEXP
타입: string 기본값: (?i)(?:p(?:ass)?w(?:or)?d|pass(?:[_-]?phrase)?|secret(?:[_-]?key)?|(?:(?:api|private|public|access)[_-]?)key(?:[_-]?id)?|(?:(?:auth|access|id|refresh)[_-]?)?token|consumer[_-]?(?:id|key|secret)|sign(?:ed|ature)?|auth(?:entication|orization)?|jsessionid|phpsessid|asp\\.net(?:[_-]|-)sessionid|sid|jwt)(?:\\s*=([^;&]+)|\"\\s*:\\s*(\"[^\"]+\"|\\d+))|bearer\\s+([a-z0-9\\._\\-]+)|token\\s*:\\s*([a-z0-9]{13})|gh[opsu]_([0-9a-zA-Z]{36})|ey[I-L][\\w=-]+\\.(ey[I-L][\\w=-]+(?:\\.[\\w.+\\/=-]+)?)|[\\-]{5}BEGIN[a-z\\s]+PRIVATE\\sKEY[\\-]{5}([^\\-]+)[\\-]{5}END[a-z\\s]+PRIVATE\\sKEY|ssh-rsa\\s*([a-z0-9\\/\\.+]{100,}) 공격 보고서에서 값으로 민감한 데이터를 편집하는 정규식 문자열.
DD_APPSEC_RASP_ENABLED
타입: boolean 기본값: true 트레이서의 RASP / Exploit Prevention 기능을 켜요. 활성화하면 트레이서가 동기식 사전 실행 검사를 실행하고 차단 액션 또는 익스플로잇 신호를 생성할 수 있어요. RASP는 언어별로 별도의 활성화·구현 세부 사항이 있을 수 있어요. 활성화하면 일반적으로 추가 동기식 계측과 감지에 대한 추가 증거 캡처가 활성화돼요.
DD_APPSEC_RAW_RESPONSE_BODY_ENABLED
타입: boolean 기본값: false 버전: v1.24.0 활성화하면 파싱된 표현과 함께 원시(파싱되지 않은) HTTP 응답 본문을 WAF로 보내요. 데이터 볼륨 증가로 인해 기본적으로 비활성화돼 있어요. 구조화된 파싱에 의존할 수 없는 WAF 규칙에 원시 본문 검사가 필요할 때만 활성화하세요.
DD_APPSEC_RULES
타입: string 트레이서에 포함된 기본 AppSec 규칙을 재정의하는 JSON 규칙 파일 경로.
DD_APPSEC_SCA_ENABLED
타입: boolean 기본값: false 트레이서의 런타임 SCA(Software Composition Analysis)를 활성화해 런타임 의존성/SBOM 데이터를 보고하고 런타임 취약점 감지를 지원해요. SCA에는 SCA 문서에 설명된 청구 영향과 언어 호환성 제약이 있을 수 있어요.
DD_APPSEC_STACK_TRACE_ENABLED
타입: boolean 기본값: true 별칭: DD_APPSEC_STACK_TRACE_ENABLE AppSec 보안 이벤트에 첨부된 스택 트레이스 생성을 활성화해요. 이벤트 페이로드에서 스택 트레이스를 생략하려면 비활성화하세요.
DD_APPSEC_TRACE_RATE_LIMIT
타입: int 기본값: 100 초당 AppSec 트레이스의 최대 수를 제어해요.
DD_APPSEC_WAF_TIMEOUT
타입: int 기본값: 10000 WAF 동기식 실행 시간(마이크로초)을 제한해요.
폐기된 키 (Retired keys)
(2)
이 키는 현재 라이브러리 버전에서 더 이상 지원되지 않아요. 더 오래된 버전을 실행 중이라면 참고로 나열한 것이에요.
DD_APPSEC_HELPER_RUST_REDIRECTION
1.17.1에서 제거됨. 타입: boolean 기본값: false 구성된 헬퍼 위치 옆에 새 rust appsec 헬퍼 라이브러리가 있는지 찾아 대신 로드할지 여부.
DD_APPSEC_HELPER_RUST_REDIRECTION
1.19.0에서 제거됨. 타입: boolean 기본값: true 버전: v1.17.1 구성된 헬퍼 위치 옆에 새 rust appsec 헬퍼 라이브러리가 있는지 찾아 대신 로드할지 여부.
Dynamic Instrumentation 및 디버깅
(9)
원격 디버깅 기능: 라이브 프로브용 Dynamic Instrumentation, 자동 변수 캡처용 Exception Replay, 소스 수준 디버깅용 Symbol Database, 스팬을 소스 코드에 연결하는 Code Origin for Spans.
DD_CODE_ORIGIN_FOR_SPANS_ENABLED
타입: boolean 기본값: true 트레이서에서 스팬용 코드 출처 동작을 활성화해요. 비활성화하면 관련 데이터 수집과 처리가 건너뛰어져요.
DD_CODE_ORIGIN_MAX_USER_FRAMES
타입: int 기본값: 8 스팬용 코드 출처(Dynamic Instrumentation): 코드 출처를 기록할 때 캡처/고려할 최대 사용자 스택 프레임 수를 설정해요(기본값: 8). 참고: 현재 코드 출처 레코더는 이 값을 읽지만 사용하지 않으므로 이 버전에서는 효과가 없을 수 있어요.
DD_DYNAMIC_INSTRUMENTATION_CAPTURE_TIMEOUT_MS
타입: int 기본값: 15 버전: v1.24.0 스냅샷 수집 중 변수 값을 캡처하는 타임아웃(밀리초).
DD_DYNAMIC_INSTRUMENTATION_ENABLED
타입: boolean 기본값: false Dynamic Instrumentation을 활성화해 재배포 없이 Datadog UI에서 실행 중인 서비스에 로그 프로브와 메트릭 프로브를 추가할 수 있게 해 줘요.
DD_DYNAMIC_INSTRUMENTATION_REDACTED_IDENTIFIERS
타입: array 캡처된 스냅샷 데이터에서 편집할 추가 식별자 키워드의 쉼표 구분 목록.
DD_DYNAMIC_INSTRUMENTATION_REDACTED_TYPES
타입: array 동적 로그와 스냅샷에서 편집할 객체 타입의 쉼표 구분 목록. * 와일드카드를 지원해요(예: Secret*는 SecretKey와 일치).
DD_DYNAMIC_INSTRUMENTATION_REDACTION_EXCLUDED_IDENTIFIERS
타입: array 버전: v1.19.0 편집에서 식별자를 제외하는 환경 변수.
DD_EXCEPTION_REPLAY_CAPTURE_INTERVAL_SECONDS
타입: int 기본값: 3600 Exception Replay: 동일한 예외 지문을 다시 캡처하기까지의 최소 간격(초). 동일한 예외의 반복 캡처를 비율 제한하는 데 사용돼요. 기본값: 3600초.
DD_EXCEPTION_REPLAY_ENABLED
타입: boolean 기본값: false Exception Replay(Live Debugging): Exception Replay 제품을 활성화해요. 활성화하면(예: Remote Config를 통해) 트레이서가 Exception Replay 하위 시스템을 시작/중지해요. 이 키는 DD_EXCEPTION_DEBUGGING_ENABLED에 대한 하위 호환 별칭으로도 받아들여져요.
CI 가시성 (CI Visibility)
(1)
CI Visibility 및 Test Optimization: 테스트 보고, 코드 커버리지 수집, Git 메타데이터, 플래키 테스트 관리, 테스트 건너뛰기, CI 공급자 통합.
DD_TRACE_GIT_METADATA_ENABLED
타입: boolean 기본값: true 활성화하면 트레이서가 Git 저장소 URL과 커밋 SHA 태그를 루트 스팬에 부착해 트레이스를 Datadog UI의 해당 소스 코드에 연결할 수 있게 해 줘요.
크래시 추적 및 진단 (Crash Tracking & Diagnostics)
(1)
애플리케이션 크래시를 캡처·보고하기 위한 크래시 추적과 힙 스냅샷 구성.
DD_CRASHTRACKING_ENABLED
타입: boolean 기본값: true 크래시 추적(Crash Tracking)을 활성화해요. 활성화하면 트레이서가 크래시 추적을 초기화하고 hs_err_pid*.log 크래시 로그와 OOME 알림을 업로드하는 Datadog 제공 스크립트를 실행하도록 JVM 크래시/OOM 훅(예: -XX:OnError, -XX:OnOutOfMemoryError)을 구성해요. 기본값: true.
로그 제출 및 상관관계 (Log Submission & Correlation)
(1)
Datadog로 직접 로그 제출, 에이전트 없는 로그 전달, 트레이스-로그 상관관계를 위한 로그 주입, OpenTelemetry 로그 내보내기.
DD_LOGS_OTEL_ENABLED
타입: boolean 기본값: false 버전: v1.20.0 OpenTelemetry Logs API를 통해 생성된 로그의 수집과 내보내기를 활성화해요.
런타임 메트릭 (Runtime Metrics)
(3)
런타임 메트릭 수집과 메트릭 제출을 위한 DogStatsD 연결 구성.
DD_DOGSTATSD_HOST
타입: string 기본값: localhost 별칭: DD_DOGSTATSD_HOSTNAME 기본 트레이서가 DogStatsD 메트릭을 제출하려 시도하는 Trace Agent 호스트의 주소를 재정의해요. DD_DOGSTATSD_HOST를 재정의하려면 DD_AGENT_HOST를 사용하세요.
DD_DOGSTATSD_PORT
타입: int 기본값: 8125 메트릭이 제출되는 DogStatsD Agent의 포트예요. Agent 구성에서 dogstatsd_port 또는 DD_DOGSTATSD_PORT를 기본값 8125이 아닌 값으로 설정했다면 이 트레이싱 라이브러리의 DD_DOGSTATSD_PORT가 그 값과 일치해야 해요.
DD_DOGSTATSD_URL
타입: string 기본값: http://localhost:8125 DogStatsD 엔드포인트에 연결하는 데 사용되는 URL이에요. DD_AGENT_HOST와 DD_DOGSTATSD_PORT보다 우선해요. udp:// 또는 unix:// 스킴만 지원해요.
계측 텔레메트리 (Instrumentation Telemetry)
(2)
트레이서 자체 보고 텔레메트리: 하트비트 간격, 의존성·로그 수집, 텔레메트리 전달자 구성.
DD_INSTRUMENTATION_TELEMETRY_ENABLED
타입: boolean 기본값: true Datadog가 제품을 개선하기 위해 애플리케이션과 런타임에 대한 환경·진단 정보를 수집할 수 있게 해 줘요. 계측 텔레메트리에서 제외하려면 false로 설정하세요.
DD_TELEMETRY_LOG_COLLECTION_ENABLED
타입: boolean 기본값: true 내부 트레이서 로그가 계측 텔레메트리의 일부로 전달되는지 제어해요.
원격 구성 (Remote Configuration)
(1)
Datadog에서 라이브 구성 업데이트를 받기 위한 원격 구성.
DD_REMOTE_CONFIG_ENABLED
타입: boolean 기본값: true 트레이서에서 Remote Config 폴링을 활성화해요(원격 구성 엔드포인트에서 구성 업데이트를 가져와 구독된 제품에 적용해요). 기본값: true.
OpenTelemetry 호환성 (OpenTelemetry Compatibility)
(28)
Datadog SDK가 지원하는 표준 OpenTelemetry 환경 변수: 리소스 속성, 프로파게이터, 트레이스 샘플러, OTLP exporter 구성, 배치 스팬 프로세서 설정.
DD_METRICS_OTEL_ENABLED
타입: boolean 기본값: false OpenTelemetry 메트릭 내보내기를 활성화해요. 메트릭은 기본적으로 비활성화되어 있으며 이 값이 참값으로 설정된 경우에만 활성화돼요.
DD_TRACE_OTEL_ENABLED
타입: boolean 기본값: false 트레이스에 대한 Datadog SDK의 OpenTelemetry 상호운용성을 활성화해요.
OTEL_BLRP_EXPORT_TIMEOUT
타입: int 기본값: 30000 버전: v1.23.0 단일 OTLP 로그 내보내기 요청이 취소되기 전까지 허용되는 최대 시간(밀리초).
OTEL_BLRP_MAX_EXPORT_BATCH_SIZE
타입: int 기본값: 512 버전: v1.23.0 단일 OTLP 페이로드의 최대 레코드 수. 최대 큐 크기보다 작거나 같아야 해요.
OTEL_BLRP_MAX_QUEUE_SIZE
타입: int 기본값: 2048 버전: v1.23.0 메모리에 보관되는 최대 로그 레코드 수. 이 한도에 도달하면 새 레코드는 버려져요.
OTEL_BLRP_SCHEDULE_DELAY
타입: int 기본값: 1000 버전: v1.23.0 두 연속 OTLP 로그 내보내기 작업 사이의 간격(밀리초).
OTEL_EXPORTER_OTLP_ENDPOINT
타입: string 기본값: http://localhost:4318 버전: v1.23.0 OpenTelemetry 메트릭 내보내기가 사용하는 OTLP exporter 엔드포인트를 설정해요. 설정하면 Agent 구성에서 파생된 기본 엔드포인트를 재정의해요.
OTEL_EXPORTER_OTLP_HEADERS
타입: map 버전: v1.23.0 OTLP 내보내기용 사용자 지정 헤더를 설정하는 구성 키예요(메트릭별 헤더의 대체값). 메트릭별 OTLP 헤더가 설정되지 않았을 때 사용돼요. 형식: api-key=key,other=value.
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
타입: string 기본값: http://localhost:4318 버전: v1.23.0 선택적으로 지정된 포트 번호가 있는 로그 데이터 전용 엔드포인트 URL. OTLP/HTTP 사용 시 일반적으로 v1/logs로 끝나요.
OTEL_EXPORTER_OTLP_LOGS_HEADERS
타입: map 버전: v1.23.0 별칭: OTEL_EXPORTER_OTLP_HEADERS 모든 나가는 OTLP 로그에 적용할 헤더 맵.
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL
타입: string 기본값: http/protobuf 버전: v1.23.0 별칭: OTEL_EXPORTER_OTLP_PROTOCOL 로그 데이터에 사용할 OTLP 전송 프로토콜을 지정해요.
OTEL_EXPORTER_OTLP_LOGS_TIMEOUT
타입: int 기본값: 10000 버전: v1.23.0 별칭: OTEL_EXPORTER_OTLP_TIMEOUT 단일 나가는 OTLP 로그 요청의 타임아웃(밀리초)을 지정해요. 일반 OTEL_EXPORTER_OTLP_TIMEOUT보다 우선해요.
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
타입: string 기본값: http://localhost:4318 버전: v1.23.0 OTLP 메트릭을 보내는 URL이에요. OTEL_EXPORTER_OTLP_ENDPOINT보다 우선해요. gRPC의 기본값은 http://localhost:4317, HTTP의 기본값은 http://localhost:4318/v1/metrics이에요. HTTP 프로토콜의 경우 일반 OTEL_EXPORTER_OTLP_ENDPOINT를 대체값으로 사용하면 SDK가 자동으로 /v1/metrics를 추가해요.
OTEL_EXPORTER_OTLP_METRICS_HEADERS
타입: map 버전: v1.23.0 나가는 OTLP 메트릭 요청의 헤더로 사용할 키-값 쌍의 쉼표 구분 목록을 지정해요(예: api-key=key,other-config=value). 일반 OTEL_EXPORTER_OTLP_HEADERS보다 우선해요.
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL
타입: string 기본값: http/protobuf 버전: v1.23.0 별칭: OTEL_EXPORTER_OTLP_PROTOCOL OpenTelemetry OTLP 메트릭 내보내기에 사용되는 프로토콜을 선택해요. http/protobuf만 지원돼요.
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE
타입: string 기본값: cumulative 버전: v1.23.0 설명: 각 계측 종류에 사용할 집계 temporality를 지정해요.
OTEL_EXPORTER_OTLP_METRICS_TIMEOUT
타입: int 기본값: 10000 버전: v1.23.0 별칭: OTEL_EXPORTER_OTLP_TIMEOUT 단일 나가는 OTLP 메트릭 요청의 타임아웃(밀리초). OTEL_EXPORTER_OTLP_TIMEOUT보다 우선해요.
OTEL_EXPORTER_OTLP_PROTOCOL
타입: string 기본값: http/protobuf 버전: v1.23.0 재정의되지 않는 한 모든 신호에 사용할 전송 프로토콜을 지정해요. 허용 값: grpc, http/protobuf, http/json.
OTEL_EXPORTER_OTLP_TIMEOUT
타입: int 기본값: 10000 버전: v1.23.0 OTLP 내보내기 요청의 기본 타임아웃(밀리초)이에요. 신호별 타임아웃이 설정되지 않았을 때 대체값으로 사용돼요.
OTEL_LOG_LEVEL
타입: string 기본값: info 버전: v1.23.0 로그 수준을 설정하는 구성 키.
OTEL_LOGS_EXPORTER
타입: array 기본값: otlp 버전: v1.23.0 OTLP 로그 내보내기를 지원하는 Datadog SDK는 otlp를 기본값으로 해야 하고, 그 외에는 모두 None/null을 기본값으로 해야 해요.
OTEL_METRIC_EXPORT_INTERVAL
타입: int 기본값: 60000 버전: v1.23.0 메트릭 내보내기 시도 사이의 간격(밀리초).
OTEL_METRIC_EXPORT_TIMEOUT
타입: int 기본값: 30000 버전: v1.23.0 단일 메트릭 배치를 수집·내보내는 데 허용되는 최대 시간(밀리초).
OTEL_METRICS_EXPORTER
타입: array 기본값: otlp 버전: v1.23.0 OpenTelemetry 메트릭 exporter를 지정해요. 허용 값은 otlp와 none뿐이에요. none으로 설정하면 OTel 메트릭 방출과 APM 런타임 메트릭을 모두 비활성화해요(DD_RUNTIME_METRICS_ENABLED=false와 동일).
OTEL_PROPAGATORS
타입: array 기본값: tracecontext,baggage 버전: v1.23.0 추출과 주입 모두에 대한 트레이스 컨텍스트 전파 형식을 지정해요(쉼표 구분 목록). 우선순위가 가장 낮으며, 다른 Datadog 트레이스 컨텍스트 전파 환경 변수가 설정되면 무시돼요.
OTEL_RESOURCE_ATTRIBUTES
타입: map 버전: v1.23.0 OpenTelemetry 리소스 속성을 (key, value) 쌍 목록으로 설정해요. 참고: 퍼센트 인코딩된 쉼표와 등호 구분자는 그대로 리터럴로 유지돼요.
OTEL_TRACES_EXPORTER
타입: array 기본값: otlp 버전: v1.23.0 OTLP 트레이스용 exporter를 설정하는 구성 키. otlp와 none 값만 인식해요.
OTEL_TRACES_SAMPLER
타입: string 기본값: parentbased_always_on 버전: v1.23.0 SDK가 트레이스를 샘플링하는 데 사용하는 Sampler를 지정해요.
계측 및 플랫폼 (Instrumentation & Platform)
(1)
계측 설정과 플랫폼별 구성: 자동 주입, 타사 라이브러리 감지, 플랫폼 어댑터.
DD_INJECT_FORCE
타입: boolean 기본값: false SSI(Single Step Instrumentation): 여러 JVM 에이전트가 감지되어도 트레이서 javaagent가 로드되도록 강제해요. 이는 여러 에이전트 실행을 피하기 위해 시작을 중단시키는 SSI 가드레일을 우회해요. DD_INJECT_FORCE 또는 시스템 속성 dd.inject.force로 설정할 수 있어요. 기본값: false.
기타 (Miscellaneous)
(2)
아직 다른 범주에 맞지 않는 구성 키. 이 목록을 백로그로 취급하세요: 각 키는 결국 실제 위치를 찾아야 해요.
DD_EXPERIMENTAL_FLAGGING_PROVIDER_ENABLED
타입: boolean 기본값: false 버전: v1.21.0 원격 구성에서 플래그를 평가하는 실험적 기능 플래그 공급자를 활성화해요. 활성화하지 않으면 이 공급자는 no-op이며 기본값을 반환해요.
DD_EXPERIMENTAL_FLAGGING_PROVIDER_SPAN_ENRICHMENT_ENABLED
타입: boolean 기본값: false 버전: v1.24.0 기능 플래그 데이터로 스팬 보강을 활성화할지 여부. 활성화되고 기능 플래그가 평가되면 기능 플래그 평가와 트레이스 간의 상관관계를 위해 관련 메타데이터가 루트 APM 스팬에 부착돼요.
통합 이름 (Integration names)
다음 표는 각 통합의 기본 서비스 이름을 지정해요. DD_SERVICE_MAPPING으로 서비스 이름을 변경하세요.
DD_TRACE_<INTEGRATION>_ENABLED 같은 통합별 구성 설정 시 이 이름을 사용하세요. 예: Laravel은 DD_TRACE_LARAVEL_ENABLED.
| 통합 | 서비스 이름 |
|---|---|
| AMQP | amqp |
| CakePHP | cakephp |
| CodeIgniter | codeigniter |
| cURL | curl |
| ElasticSearch | elasticsearch |
| Eloquent | eloquent |
| Guzzle | guzzle |
| Laminas | laminas |
| Laravel | laravel |
| Laravel Queue | laravelqueue |
| Lumen | lumen |
| Memcache | memcache |
| Memcached | memcached |
| Mongo | mongo |
| MongoDB | mongodb |
| Mysqli | mysqli |
| Nette | nette |
| OpenAI | openai |
| PCNTL | pcntl |
| PDO | pdo |
| PhpRedis | phpredis |
| Predis | predis |
| Psr18 | psr18 |
| Roadrunner | roadrunner |
| Sql Server | sqlsrv |
| Symfony | symfony |
| Symfony Messenger | symfonymessenger |
| WordPress | wordpress |
| Yii | yii |
| ZendFramework | zendframework |
리소스 이름을 정규화된 URI로 매핑 (Map resource names to normalized URI)
DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX, DD_TRACE_RESOURCE_URI_MAPPING_INCOMING, DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING 중 하나라도 설정하면 새로운 리소스 정규화 접근 방식이 적용되고 DD_TRACE_RESOURCE_URI_MAPPING의 값은 무시된다는 점을 참고하세요.
HTTP 서버·클라이언트 통합의 경우, URL이 <HTTP_REQUEST_METHOD> <NORMALIZED_URL> 형식으로 트레이스 리소스 이름을 만드는 데 사용되고 쿼리 문자열은 URL에서 제거돼요. 이는 URL을 정규화하고 일반 엔드포인트를 하나의 리소스로 묶어, 자동 계측되지 않는 사용자 지정 프레임워크에서 더 나은 가시성을 제공해요.
| HTTP 요청 | 리소스 이름 |
|---|---|
/foo?a=1&b=2에 대한 GET 요청 |
GET /foo |
/bar?foo=bar에 대한 POST 요청 |
POST /bar |
숫자 ID, UUID(대시 유무와 관계없이), 32~512비트 hex 해시는 자동으로 ? 문자로 대체돼요.
| URL (GET 요청) | 리소스 이름 |
|---|---|
/user/123/show |
GET /user/?/show |
/widget/b7a992e0-3300-4030-8617-84553b11c993 |
GET /widget/? |
/api/v2/b7a992e033004030861784553b11c993/123 |
GET /api/v2/?/? |
/book/0dbf3596 |
GET /book/? |
DD_TRACE_URL_AS_RESOURCE_NAMES_ENABLED=0으로 이 기능을 끌 수 있어요.
사용자 지정 URL-리소스 매핑 (Custom URL-to-resource mapping)
자동 정규화로 처리되지 않는 몇 가지 경우가 있어요.
| URL (GET 요청) | 예상 리소스 이름 |
|---|---|
/using/prefix/id123/for/id |
GET /using/prefix/?/for/id |
/articles/slug-of-title |
GET /articles/? |
/cities/new-york/rivers |
GET /cities/?/rivers |
/nested/cities/new-york/rivers |
GET /nested/cities/?/rivers |
자동 정규화로 처리되지 않는 시나리오의 두 가지 유형이 있어요:
- 정규화할 경로 조각이 재현 가능한 패턴을 가지며 URL의 어느 부분에도 있을 수 있는 경우(예: 위 예시의
id<number>). 이 시나리오는 아래DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX설정으로 처리돼요. - 경로 조각이 무엇이든 될 수 있고 이전 경로 조각이 값이 정규화되어야 함을 나타내는 경우. 예를 들어
/cities/new-york은new-york이 도시 이름이므로 정규화되어야 함을 알려 줘요. 이 시나리오는 들어오는 요청에는DD_TRACE_RESOURCE_URI_MAPPING_INCOMING, 나가는 요청에는DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING설정으로 처리돼요.
DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX
이 설정은 각 경로 조각에 독립적으로 적용되는 하나 이상의 정규식의 CSV예요. 예를 들어 /using/prefix/id123/for/id 경로에 DD_TRACE_RESOURCE_URI_FRAGMENT_REGEX를 ^id\\d+$로 설정하면 정규식이 using, prefix, id123, for, id 각 조각에 적용돼요.
| URL | regex | 예상 리소스 이름 |
|---|---|---|
/using/prefix/id123/for/id |
^id\\d+$ |
GET /using/prefix/?/for/id |
이 변수의 형식이 CSV이므로 쉼표 문자 ,는 이스케이프되지 않으며 정규식에 사용할 수 없다는 점을 참고하세요.
DD_TRACE_RESOURCE_URI_MAPPING_INCOMING 및 DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING
이 설정은 와일드카드 *를 포함할 수 있는 패턴의 CSV예요. 예를 들어 cities/* 패턴을 추가하면 URL을 분석할 때 cities 조각이 발견될 때마다 다음 조각이 있으면 ?로 대체돼요. 패턴은 어떤 깊이에서든 적용되므로, 다음 규칙을 적용하면 위 표의 /cities/new-york과 /nested/cities/new-york을 모두 정규화해요.
패턴은 특정 조각의 일부에 적용될 수 있어요. 예를 들어 path/*-fix는 URL /some/path/changing-fix/nested를 /some/path/?-fix/nested로 정규화해요.
참고: DD_TRACE_RESOURCE_URI_MAPPING_INCOMING은 들어오는 요청(예: 웹 프레임워크)에만 적용되고, DD_TRACE_RESOURCE_URI_MAPPING_OUTGOING은 나가는 요청(예: curl, guzzle 요청)에만 적용돼요.
open_basedir 제한
open_basedir 설정을 사용할 때는 /opt/datadog-php를 허용된 디렉터리 목록에 추가해야 해요. 애플리케이션이 Docker 컨테이너에서 실행될 때는 /proc/self 경로도 허용된 디렉터리 목록에 추가해야 해요.
더 알아보기 (Learn more)
- Datadog APM과 분산 트레이싱으로 PHP 모니터링 (PHP monitoring with Datadog APM and distributed tracing)
- 소스 코드 (Source code)
- 트레이스 컨텍스트 전파 (Propagating trace context)
- 서비스·리소스·트레이스 탐색 (Explore your services, resources and traces)
- 고급 사용법 (Advanced Usage)
- OpenTelemetry 환경 변수 구성 (OpenTelemetry Environment Variable Configurations)