C++ SDK 구성 (Configuring the C++ SDK)

원문 보기 위키 갱신 2026.10.05

C++ SDK를 코드와 함께 설정하고 Agent가 APM 데이터를 수집하도록 구성한 뒤, 필요에 따라 SDK를 원하는 대로 구성하는 방법을 안내해요. 여기에는 Unified Service Tagging 설정도 포함돼요.

출처: 문서

본문

런타임 구성을 확인하고 설정을 검증하려면 Datadog에서 서비스의 현재 구성을 확인하세요. APM Service Page로 이동해 Service Config를 클릭하고 SDK Configuration 탭을 선택하세요.

서비스의 env, service, version을 설정하려면 DD_SERVICE, DD_ENV, DD_VERSION을 사용하는 것이 좋아요. 환경 변수에 어떤 값을 설정해야 하는지에 대한 권장 사항은 Unified Service Tagging 문서를 참고하세요.

환경 변수로 SDK를 구성하려면 계측된 애플리케이션을 시작하기 전에 변수를 설정하세요.

구성 키 (Configuration keys)

이 라이브러리에 사용 가능한 구성 키는 36개예요.

일반 설정 (General Settings)

(7)

최상위 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_ENV

타입: string 트레이서가 내보내는 모든 텔레메트리(트레이스, 메트릭, 로그, 프로파일)에 적용되는 전역 env 태그를 설정해요. prod, staging, dev 같은 환경을 구분하는 데 사용해요.

DD_EXTERNAL_ENV

타입: string 내보낸 텔레메트리에 부착되는 외부 환경 식별자를 설정해 출처와 환경 귀속에 사용해요.

DD_SERVICE

타입: string 애플리케이션의 서비스 이름을 설정해요.

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)

(8)

핵심 분산 트레이싱 엔진: Agent 연결, 트레이스·스팬 ID 생성, 스팬 수명주기 관리, 피어 서비스 매핑, 리소스 정규화, 쿼리 문자열 난독화, DB 클라이언트 구성.

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_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_URL

타입: string 별칭: DD_TRACE_URL 트레이스가 전송되는 URL 엔드포인트를 설정해요. 설정하면 DD_AGENT_HOST와 DD_TRACE_AGENT_PORT를 재정의해요. 기본값은 http://<DD_AGENT_HOST>:<DD_TRACE_AGENT_PORT>이에요.

DD_TRACE_ENABLED

타입: boolean 기본값: true 별칭: DD_TRACING_ENABLED 프레임워크 및 라이브러리 계측을 활성화해요. false로 설정하면 애플리케이션 코드가 트레이스를 생성하지 않아요. DD_APM_TRACING_ENABLED도 참고하세요.

DD_TRACE_REPORT_HOSTNAME

타입: boolean 기본값: false 각 트레이스에 대해 시스템 호스트명을 보고할지 여부예요. 비활성화하면 대신 Agent의 호스트명이 사용돼요.

DD_TRACE_RESOURCE_RENAMING_ALWAYS_SIMPLIFIED_ENDPOINT

타입: boolean 기본값: false 버전: v2.1.0 활성화하면 명시적 엔드포인트를 사용할 수 있을 때에도 항상 http.endpoint 태그를 Resource Renaming 단순화 알고리즘의 결과로 설정해요.

DD_TRACE_RESOURCE_RENAMING_ENABLED

타입: boolean 기본값: false 버전: v2.1.0 들어오는 HTTP 요청에 대해 http.endpoint 태그를 계산해 추가할지 제어해요. 기본적으로 애플리케이션 보안이 시작 시 활성화되지 않는 한 비활성화되어 있고, 이 설정으로 명시적으로 활성화하거나 비활성화할 수 있어요.

DD_TRACE_TAGS_PROPAGATION_MAX_LENGTH

타입: int 기본값: 512 전파를 위해 트레이스 컨텍스트를 주입할 때 직렬화된 x-datadog-tags 헤더의 최대 크기(바이트)예요. 인코딩된 태그가 이 한도를 초과하면 헤더가 기록되지 않고 전파 오류 태그가 설정돼요.

트레이스 샘플링 (Trace Sampling)

(5)

어떤 트레이스와 스팬을 유지하거나 버릴지 결정하는 샘플링 규칙과 비율. 서비스별 규칙, 비율 제한, 우선순위 샘플링을 포함해요.

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}]

트레이스 전파 (Trace Propagation)

(8)

분산 트레이스 컨텍스트 전파, 추출·주입 동작, 배기지(baggage) 처리, 헤더 태깅, HTTP 클라이언트·서버 구성, Database Monitoring을 위한 SQL 주석 주입.

DD_PROPAGATION_STYLE_EXTRACT

타입: array 기본값: datadog,tracecontext,baggage 분산 트레이싱 전파 데이터를 추출하려 시도할 헤더 형식의 쉼표 구분 목록이에요. 완전하고 유효한 헤더가 있는 첫 번째 형식이 계속할 트레이스를 정의하는 데 사용돼요. DD_TRACE_PROPAGATION_STYLE_EXTRACT가 설정되면 적용되지 않아요.

DD_PROPAGATION_STYLE_INJECT

타입: array 기본값: datadog,tracecontext,baggage 서비스 간 분산 트레이스를 전파하기 위해 포함할 헤더 형식의 쉼표 구분 목록이에요. 완전하고 유효한 헤더가 있는 첫 번째 형식이 계속할 트레이스를 정의하는 데 사용돼요. DD_TRACE_PROPAGATION_STYLE_INJECT가 설정되면 적용되지 않아요.

DD_TRACE_BAGGAGE_MAX_BYTES

타입: int 기본값: 8192 다운스트림 서비스로 전파할 때 baggage 헤더에 주입할 수 있는 최대 바이트 수를 설정하는 구성 키예요. 기본값은 8192바이트예요.

DD_TRACE_BAGGAGE_MAX_ITEMS

타입: int 기본값: 64 다운스트림 서비스로 전파할 때 baggage 헤더에 주입할 수 있는 최대 항목 수를 설정하는 구성 키예요. 기본값은 64개 항목이에요.

DD_TRACE_PROPAGATION_BEHAVIOR_EXTRACT

타입: string 기본값: continue 버전: v2.2.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,baggage 별칭: DD_PROPAGATION_STYLE_EXTRACT, DD_TRACE_PROPAGATION_STYLE 분산 트레이싱 전파 데이터를 추출하려 시도할 헤더 형식의 쉼표 구분 목록이에요. 완전하고 유효한 헤더가 있는 첫 번째 형식이 계속할 트레이스를 정의하는 데 사용돼요.

DD_TRACE_PROPAGATION_STYLE_INJECT

타입: array 기본값: datadog,tracecontext,baggage 별칭: DD_PROPAGATION_STYLE_INJECT, DD_TRACE_PROPAGATION_STYLE 서비스 간 분산 트레이스를 전파하기 위해 포함할 헤더 형식의 쉼표 구분 목록이에요. 완전하고 유효한 헤더가 있는 첫 번째 형식이 계속할 트레이스를 정의하는 데 사용돼요.

트레이스 로깅 (Trace Logging)

(2)

트레이서 로그 출력 설정: 로그 수준, 로그 파일 경로, 로그 회전, 시작 진단.

DD_TRACE_DEBUG

타입: boolean 기본값: false 별칭: OTEL_LOG_LEVEL SDK의 디버그 모드를 활성화해요. 설정하면 SDK가 문제 해결을 위해 자세한 로그 메시지를 내보내요. 활성화되면 DD_TRACE_LOG_LEVEL보다 우선해요. OTEL_LOG_LEVEL을 별칭으로 사용하세요.

언어별 참고:

PHP: 로그 메시지는 PHP error_log INI 설정에 지정된 장치나 파일에 기록돼요. 실제 값은 PHP-FPM/Apache 구성 파일에서 재정의될 수 있어 php -i 출력과 다를 수 있어요.

DD_TRACE_STARTUP_LOGS

타입: boolean 기본값: true 트레이서가 초기화될 때 시작 구성과 진단 로그 줄의 생성을 활성화해요.

계측 텔레메트리 (Instrumentation Telemetry)

(5)

트레이서 자체 보고 텔레메트리: 하트비트 간격, 의존성·로그 수집, 텔레메트리 전달자 구성.

DD_INSTRUMENTATION_TELEMETRY_ENABLED

타입: boolean 기본값: true Datadog가 제품을 개선하기 위해 애플리케이션과 런타임에 대한 환경·진단 정보를 수집할 수 있게 해 줘요. 계측 텔레메트리에서 제외하려면 false로 설정하세요.

DD_TELEMETRY_DEBUG

타입: boolean 기본값: false 계측 텔레메트리의 디버그 모드를 활성화해요. 설정하면 다른 구성과 무관하게 텔레메트리 디버그 모드를 강제로 켜요.

DD_TELEMETRY_LOG_COLLECTION_ENABLED

타입: boolean 기본값: true 내부 트레이서 로그가 계측 텔레메트리의 일부로 전달되는지 제어해요.

DD_TELEMETRY_METRICS_ENABLED

타입: boolean 기본값: true 계측 텔레메트리가 내부 메트릭을 보내는지 제어해요.

DD_TELEMETRY_METRICS_INTERVAL_SECONDS

타입: decimal 기본값: 60 트레이서가 Datadog Agent에 메트릭을 보고하는 빈도를 제어해요.

원격 구성 (Remote Configuration)

(1)

Datadog에서 라이브 구성 업데이트를 받기 위한 원격 구성.

DD_REMOTE_CONFIGURATION_ENABLED

타입: boolean 기본값: true 별칭: DD_REMOTE_CONFIG_ENABLED 원격 구성을 활성화하거나 비활성화해요.