수집 메커니즘 (Ingestion Mechanisms)

애플리케이션이 생성한 스팬이 Datadog로 보내지는지(수집되는지) 여부는 여러 메커니즘이 결정해요. 이 메커니즘의 로직은 SDK와 Datadog Agent에 있어요. 구성에 따라 계측된 서비스가 생성하는 모든 트래픽 또는 일부 트래픽이 수집돼요.

출처: 문서

본문

개요 (Overview)

여러 메커니즘이 애플리케이션에서 생성된 스팬이 Datadog로 보내지는지(수집되는지) 결정해요. 이 메커니즘의 로직은 SDK와 Datadog Agent에 있어요. 구성에 따라 계측된 서비스가 생성한 트래픽의 전체 또는 일부가 수집돼요.

수집되는 각 스팬에는 이 페이지에 설명된 메커니즘 중 하나를 가리키는 고유한 수집 이유(ingestion reason) 가 있어요. 사용량 메트릭 datadog.estimated_usage.apm.ingested_bytes와 datadog.estimated_usage.apm.ingested_spans은 ingestion_reason으로 태깅돼요.

Ingestion Reasons 대시보드를 사용해 각 수집 이유를 맥락 속에서 조사하고 어떤 구성 옵션에 집중해야 할지 파악하세요.

헤드 기반 샘플링 (Head-based sampling)

기본 샘플링 메커니즘을 헤드 기반 샘플링(head-based sampling) 이라고 해요. 트레이스를 유지할지 드롭할지 결정은 루트 스팬 시작 시 내려지고, 요청 컨텍스트의 일부(예: HTTP 요청 헤더)로 다른 서비스에 전파돼요.

결정이 트레이스 시작 시 내려지고 모든 부분에 전달되므로 트레이스는 통째로 유지되거나 드롭돼요.

헤드 기반 샘플링의 샘플링 비율은 두 곳에서 설정할 수 있어요:

• Agent 수준(기본값)
• SDK 수준: 모든 SDK 메커니즘은 Agent 설정을 덮어써요.

Agent에서 (In the Agent)

ingestion_reason: auto

Datadog Agent는 SDK에 샘플링 비율을 지속적으로 보내 트레이스 루트에 적용해요. Agent는 트래픽에 따라 서비스에 분배해 초당 총 10개 트레이스를 목표로 비율을 조정해요.

예를 들어 서비스 A가 서비스 B보다 트래픽이 많으면 Agent는 A의 샘플링 비율을 조정해 A가 초당 7개 이하의 트레이스를 유지하고, B는 초당 3개 이하로 유지하게 해 총 초당 10개 트레이스가 되게 해요.

원격 구성 (Remote configuration)

Agent 버전 7.42.0 이상을 사용하면 Agent의 샘플링 비율 구성을 원격으로 설정할 수 있어요. 시작하려면 원격 구성(Remote Configuration)을 설정한 다음 Ingestion Control 페이지에서 ingestion_reason 파라미터를 구성하세요. 원격 구성을 사용하면 Agent를 재시작하지 않고 파라미터를 변경할 수 있어요. 원격으로 설정된 구성은 환경 변수와 datadoghq.yaml의 설정을 포함한 로컬 구성보다 우선해요.

로컬 구성 (Local configuration)

Agent의 기본 구성 파일(datadog.yaml)이나 환경 변수에서 Agent의 목표 초당 트레이스 수를 설정하세요:

@param target_traces_per_second - integer - optional - default: 10
@env DD_APM_TARGET_TPS - integer - optional - default: 10

참고:

• Agent에 설정된 초당 트레이스 수 샘플링 비율은 Datadog SDK에만 적용돼요. OpenTelemetry SDK 같은 다른 SDK에는 효과가 없어요.
• 목표는 고정된 값이 아니에요. 실제로는 트래픽 급증 등 요인에 따라 변동돼요.

Datadog Agent의 자동 샘플링 비율로 샘플링된 트레이스의 스팬은 수집 이유 auto로 태깅돼요. ingestion_reason 태그는 사용량 메트릭에도 설정돼요. 이 기본 메커니즘을 사용하는 서비스는 Ingestion Control 페이지의 Configuration 열에서 Automatic으로 표시돼요.

SDK에서: 사용자 정의 규칙 (In SDKs: user-defined rules)

ingestion_reason: rule

더 세밀한 제어를 위해 SDK 샘플링 구성 옵션을 사용하세요:

• 서비스 또는 리소스 이름별로 트레이스 루트에 적용할 특정 샘플링 비율을 설정해 Agent의 기본 메커니즘을 덮어쓰기
• 초당 수집되는 트레이스 수에 대한 비율 제한(rate limit) 설정. 기본 비율 제한은 서비스 인스턴스당 초당 100개 트레이스예요. Agent 기본 메커니즘을 사용할 때는 레이트 리미터가 무시돼요.

참고: 샘플링 규칙도 헤드 기반 샘플링 제어예요. 서비스 트래픽이 구성된 최대 초당 트레이스 수보다 많으면 트레이스가 루트에서 드롭돼요. 불완전한 트레이스는 생성되지 않아요.

구성은 환경 변수나 코드에서 직접 설정할 수 있어요:

Java

원격 구성

버전 1.34.0부터 Java 애플리케이션에서 Ingestion Control 페이지 UI에서 서비스별·리소스별 샘플링 비율을 설정할 수 있어요.

서비스와 리소스별로 샘플링 비율을 원격으로 구성하는 방법은 리소스 기반 샘플링 가이드에서 자세히 알아보세요.

참고: 원격으로 설정된 구성은 로컬 구성보다 우선해요.

로컬 구성

Java 애플리케이션에서 DD_TRACE_SAMPLING_RULES 환경 변수로 서비스별·리소스별(리소스 기반 샘플링은 버전 v1.26.0부터) 샘플링 비율을 설정하세요.

예를 들어 서비스 my-service의 리소스 GET /checkout에 대한 트레이스 100%와 다른 엔드포인트 트레이스 20%를 캡처하려면 다음과 같이 설정하세요:

# using system property
java -Ddd.trace.sampling.rules='[{"service": "my-service", "resource": "GET /checkout", "sample_rate":1},{"service": "my-service", "sample_rate":0.2}]' -javaagent:dd-java-agent.jar -jar my-app.jar

# using environment variables
export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "resource":"GET /checkout", "sample_rate": 1},{"service": "my-service", "sample_rate": 0.2}]'

서비스 이름 값은 대소문자를 구분하며 실제 서비스 이름의 대소문자와 일치해야 해요.

DD_TRACE_RATE_LIMIT 환경 변수를 서비스 인스턴스당 최대 초당 트레이스 수로 설정해 비율 제한을 구성하세요. DD_TRACE_RATE_LIMIT 값이 설정되지 않으면 초당 100개 트레이스 제한이 적용돼요.

참고: DD_TRACE_SAMPLE_RATE의 사용은 더 이상 권장되지 않아요(deprecated). 대신 DD_TRACE_SAMPLING_RULES를 사용하세요. 예를 들어 이미 DD_TRACE_SAMPLE_RATE를 0.1로 설정했다면 DD_TRACE_SAMPLING_RULES를 [{"sample_rate":0.1}]로 설정하세요.

샘플링 제어에 대한 자세한 내용은 Java SDK 문서를 참고하세요.

Python

원격 구성

버전 2.9.0부터 Python 애플리케이션에서 Ingestion Control 페이지 UI에서 서비스별·리소스별 샘플링 비율을 설정할 수 있어요.

서비스와 리소스별로 샘플링 비율을 원격으로 구성하는 방법은 리소스 기반 샘플링 가이드에서 자세히 알아보세요.

참고: 원격으로 설정된 구성은 로컬 구성보다 우선해요.

로컬 구성 Python 애플리케이션에서 DD_TRACE_SAMPLING_RULES 환경 변수로 서비스별·리소스별(리소스 기반 샘플링은 버전 v2.8.0부터) 샘플링 비율을 설정하세요.

예를 들어 서비스 my-service의 리소스 GET /checkout에 대한 트레이스 100%와 다른 엔드포인트 트레이스 20%를 캡처하려면 다음과 같이 설정하세요:

export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "resource": "GET /checkout", "sample_rate": 1},{"service": "my-service", "sample_rate": 0.2}]'

DD_TRACE_RATE_LIMIT 환경 변수를 서비스 인스턴스당 최대 초당 트레이스 수로 설정해 비율 제한을 구성하세요. DD_TRACE_RATE_LIMIT 값이 설정되지 않으면 초당 100개 트레이스 제한이 적용돼요.

참고: DD_TRACE_SAMPLE_RATE의 사용은 더 이상 권장되지 않아요. 대신 DD_TRACE_SAMPLING_RULES를 사용하세요. 예를 들어 이미 DD_TRACE_SAMPLE_RATE를 0.1로 설정했다면 DD_TRACE_SAMPLING_RULES를 [{"sample_rate":0.1}]로 설정하세요.

샘플링 제어에 대한 자세한 내용은 Python SDK 문서를 참고하세요.

Ruby

원격 구성

버전 2.0.0부터 Ruby 애플리케이션에서 Ingestion Control 페이지 UI에서 서비스별·리소스별 샘플링 비율을 설정할 수 있어요.

서비스와 리소스별로 샘플링 비율을 원격으로 구성하는 방법은 리소스 기반 샘플링 가이드에서 자세히 알아보세요.

참고: 원격으로 설정된 구성은 로컬 구성보다 우선해요.

로컬 구성 Ruby 애플리케이션에서 DD_TRACE_SAMPLE_RATE 환경 변수로 라이브러리의 전역 샘플링 비율을 설정하세요. DD_TRACE_SAMPLING_RULES 환경 변수로 서비스별 샘플링 비율을 설정하세요.

예를 들어 my-service라는 서비스의 트레이스 50%와 나머지 트레이스 10%를 보내려면:

export DD_TRACE_SAMPLE_RATE=0.1
export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "sample_rate": 0.5}]'

DD_TRACE_RATE_LIMIT 환경 변수를 서비스 인스턴스당 최대 초당 트레이스 수로 설정해 비율 제한을 구성하세요. DD_TRACE_RATE_LIMIT 값이 설정되지 않으면 초당 100개 트레이스 제한이 적용돼요.

샘플링 제어에 대한 자세한 내용은 Ruby SDK 문서를 참고하세요.

Go

원격 구성

버전 1.64.0부터 Go 애플리케이션에서 Ingestion Control 페이지 UI에서 서비스별·리소스별 샘플링 비율을 설정할 수 있어요.

서비스와 리소스별로 샘플링 비율을 원격으로 구성하는 방법은 이 문서에서 자세히 알아보세요.

참고: 원격으로 설정된 구성은 로컬 구성보다 우선해요.

로컬 구성

Go 애플리케이션에서 DD_TRACE_SAMPLING_RULES 환경 변수로 서비스별·리소스별(리소스 기반 샘플링은 버전 v1.60.0부터) 샘플링 비율을 설정하세요.

예를 들어 서비스 my-service의 리소스 GET /checkout에 대한 트레이스 100%와 다른 엔드포인트 트레이스 20%를 캡처하려면 다음과 같이 설정하세요:

export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "resource": "GET /checkout", "sample_rate": 1},{"service": "my-service", "sample_rate": 0.2}]'

DD_TRACE_RATE_LIMIT 환경 변수를 서비스 인스턴스당 최대 초당 트레이스 수로 설정해 비율 제한을 구성하세요. DD_TRACE_RATE_LIMIT 값이 설정되지 않으면 초당 100개 트레이스 제한이 적용돼요.

참고: DD_TRACE_SAMPLE_RATE의 사용은 더 이상 권장되지 않아요. 대신 DD_TRACE_SAMPLING_RULES를 사용하세요. 예를 들어 이미 DD_TRACE_SAMPLE_RATE를 0.1로 설정했다면 DD_TRACE_SAMPLING_RULES를 [{"sample_rate":0.1}]로 설정하세요.

샘플링 제어에 대한 자세한 내용은 Go SDK 문서를 참고하세요.

Node.js

원격 구성

버전 5.16.0부터 Node.js 애플리케이션에서 Ingestion Control 페이지 UI에서 서비스별·리소스별 샘플링 비율을 설정할 수 있어요.

서비스와 리소스별로 샘플링 비율을 원격으로 구성하는 방법은 리소스 기반 샘플링 가이드에서 자세히 알아보세요.

참고: 원격으로 설정된 구성은 로컬 구성보다 우선해요.

로컬 구성

Node.js 애플리케이션에서 DD_TRACE_SAMPLE_RATE 환경 변수로 라이브러리의 전역 샘플링 비율을 설정하세요.

서비스별 샘플링 비율도 설정할 수 있어요. 예를 들어 my-service라는 서비스의 트레이스 50%와 나머지 트레이스 10%를 보내려면:

tracer.init({
    ingestion: {
        sampler: {
            sampleRate: 0.1,
            rules: [
                { sampleRate: 0.5, service: 'my-service' }
            ]
        }
    }
});

DD_TRACE_RATE_LIMIT 환경 변수를 서비스 인스턴스당 최대 초당 트레이스 수로 설정해 비율 제한을 구성하세요. DD_TRACE_RATE_LIMIT 값이 설정되지 않으면 초당 100개 트레이스 제한이 적용돼요.

샘플링 제어에 대한 자세한 내용은 Node.js SDK 문서를 참고하세요.

PHP

원격 구성

버전 1.4.0부터 PHP 애플리케이션에서 Ingestion Control 페이지에서 서비스별·리소스별 샘플링 비율을 설정할 수 있어요.

서비스와 리소스별로 샘플링 비율을 원격으로 구성하는 방법은 리소스 기반 샘플링 가이드에서 자세히 알아보세요.

참고: 원격으로 설정된 구성은 로컬 구성보다 우선해요.

로컬 구성

PHP 애플리케이션에서 DD_TRACE_SAMPLE_RATE 환경 변수로 라이브러리의 전역 샘플링 비율을 설정하세요. DD_TRACE_SAMPLING_RULES 환경 변수로 서비스별 샘플링 비율을 설정하세요.

예를 들어 my-service라는 서비스의 트레이스 50%, 다른 엔드포인트 트레이스 20%, 나머지 트레이스 10%를 보내려면:

export DD_TRACE_SAMPLE_RATE=0.1
export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "resource":"GET /checkout", "sample_rate": 1},{"service": "my-service", "sample_rate": 0.2}]'

샘플링 제어에 대한 자세한 내용은 PHP SDK 문서를 참고하세요.

C++

원격 구성

버전 0.2.2부터 C++ 애플리케이션에서 Ingestion Control 페이지 UI에서 서비스별·리소스별 샘플링 비율을 설정할 수 있어요.

서비스와 리소스별로 샘플링 비율을 원격으로 구성하는 방법은 리소스 기반 샘플링 가이드에서 자세히 알아보세요.

참고: 원격으로 설정된 구성은 로컬 구성보다 우선해요.

로컬 구성 v0.1.0부터 Datadog C++ 라이브러리는 다음 구성을 지원해요:

• 전역 샘플링 비율: DD_TRACE_SAMPLE_RATE 환경 변수
• 서비스별 샘플링 비율: DD_TRACE_SAMPLING_RULES 환경 변수
• 비율 제한 설정: DD_TRACE_RATE_LIMIT 환경 변수

예를 들어 my-service라는 서비스의 트레이스 50%와 나머지 트레이스 10%를 보내려면:

export DD_TRACE_SAMPLE_RATE=0.1
export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "sample_rate": 0.5}]'

C++는 자동 계측을 위한 인테그레이션을 제공하지 않지만 Envoy, NGINX, Istio 같은 프록시 트레이싱에서 사용돼요. 프록시 샘플링 구성 방법은 Tracing proxies에서 자세히 알아보세요.

Rust

로컬 구성

Rust 애플리케이션에서 DD_TRACE_SAMPLING_RULES 환경 변수로 서비스별 샘플링 비율을 설정하세요.

예를 들어 my-service라는 서비스의 트레이스 50%와 나머지 트레이스 10%를 보내려면:

export DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "sample_rate": 0.5},{"sample_rate": 0.1}]'

DD_TRACE_RATE_LIMIT 환경 변수를 서비스 인스턴스당 최대 초당 트레이스 수로 설정해 비율 제한을 구성하세요. DD_TRACE_RATE_LIMIT 값이 설정되지 않으면 초당 100개 트레이스 제한이 적용돼요.

샘플링 제어에 대한 자세한 내용은 Rust SDK 문서를 참고하세요.

.NET

.NET 애플리케이션에서 DD_TRACE_SAMPLE_RATE 환경 변수로 라이브러리의 전역 샘플링 비율을 설정하세요. DD_TRACE_SAMPLING_RULES 환경 변수로 서비스별 샘플링 비율을 설정하세요.

예를 들어 my-service라는 서비스의 트레이스 50%와 나머지 트레이스 10%를 보내려면:

#using powershell
$env:DD_TRACE_SAMPLE_RATE=0.1
$env:DD_TRACE_SAMPLING_RULES='[{"service": "my-service", "sample_rate": 0.5}]'

#using JSON file   
{
    "DD_TRACE_SAMPLE_RATE": "0.1",
    "DD_TRACE_SAMPLING_RULES": "[{\"service\": \"my-service\", \"resource\": \"GET /checkout\", \"sample_rate\": 0.5}]"
}

참고: 버전 2.35.0부터 서비스가 실행되는 곳에서 Agent 원격 구성이 활성화되어 있으면 Catalog UI에서 서비스별 DD_TRACE_SAMPLE_RATE를 설정할 수 있어요.

DD_TRACE_RATE_LIMIT 환경 변수를 서비스 인스턴스당 최대 초당 트레이스 수로 설정해 비율 제한을 구성하세요. DD_TRACE_RATE_LIMIT 값이 설정되지 않으면 초당 100개 트레이스 제한이 적용돼요.

샘플링 제어에 대한 자세한 내용은 .NET SDK 문서를 참고하세요. .NET 환경 변수 구성에 대해 자세히 알아보세요.

참고: SDK 구성을 사용해 샘플링된 트레이스의 모든 스팬은 수집 이유 rule로 태깅돼요. 사용자 정의 샘플링 규칙으로 구성된 서비스는 Ingestion Control 페이지의 Configuration 열에서 Configured로 표시돼요.

오류 및 희귀 트레이스 (Error and rare traces)

헤드 기반 샘플링에 잡히지 않은 트레이스에 대해 두 가지 추가 Datadog Agent 샘플링 메커니즘이 그렇지 않으면 드롭될 위험한 트레이스와 다양한 트레이스를 잡아줘요. 이 샘플러는 미리 정해진 태그 집합의 모든 조합을 잡아 다양한 로컬 트레이스(같은 호스트의 스팬)를 유지해요:

• 오류 트레이스(Error traces): 오류 샘플링은 잠재적 시스템 장애에 대한 가시성을 제공해요.
• 희귀 트레이스(Rare traces): 희귀 트레이스 샘플링은 시스템 전반의 트래픽이 적은 서비스와 리소스에 대한 가시성을 유지해요.

참고: 라이브러리 샘플링 규칙을 설정한 서비스에는 오류 및 희귀 샘플러가 무시돼요.

오류 트레이스 (Error traces)

ingestion_reason: error

오류 샘플러는 헤드 기반 샘플링에 잡히지 않은 오류 스팬이 포함된 트레이스의 일부를 Agent당 초당 최대 10개 트레이스 비율로 잡아요. 헤드 기반 샘플링 비율이 낮을 때 오류에 대한 가시성을 유지하는 데 도움이 돼요.

Agent 버전 7.33부터 Agent 기본 구성 파일(datadog.yaml)이나 환경 변수로 오류 샘플러를 구성할 수 있어요:

@param errors_per_second - integer - optional - default: 10
@env DD_APM_ERROR_TPS - integer - optional - default: 10

참고:

1. 오류 샘플러를 비활성화하려면 파라미터를 0으로 설정하세요.
2. 오류 샘플러는 Agent 수준에서 로컬 오류 트레이스를 캡처해요. 트레이스가 분산되어 있으면 완전한 트레이스가 Datadog로 보내지지 않을 수 있어요.
3. 기본적으로 SDK 규칙이나 manual.drop 같은 커스텀 로직으로 드롭된 스팬은 오류 샘플러에서 제외돼요.

Datadog Agent 7.42.0 이상

Agent 버전 7.42.0 이상을 사용하면 오류 샘플링을 원격으로 구성할 수 있어요. 문서에 따라 Agent에서 원격 구성을 활성화하세요. 원격 구성을 사용하면 Datadog Agent를 재시작하지 않고 희귀 스팬 수집을 활성화할 수 있어요.

Datadog Agent 6/7.41.0 이상

기본 동작을 덮어써서 SDK 규칙이나 manual.drop 같은 커스텀 로직으로 드롭된 스팬이 오류 샘플러에 포함되도록 하려면 Datadog Agent(Kubernetes의 Datadog Agent 파드 내 전용 Trace Agent 컨테이너)에서 DD_APM_FEATURES=error_rare_sample_tracer_drop으로 기능을 활성화하세요.

Datadog Agent 6/7.33 ~ 6/7.40.x

이 Agent 버전에서는 오류 샘플링 기본 동작을 변경할 수 없어요. Datadog Agent를 Datadog Agent 6/7.41.0 이상으로 업그레이드하세요.

희귀 트레이스 (Rare traces)

ingestion_reason: rare

희귀 샘플러는 희귀 스팬 집합을 Datadog로 보내요. env, service, name, resource, error.type, http.status 조합을 Agent당 초당 최대 5개 트레이스 비율로 잡아요. 헤드 기반 샘플링 비율이 낮을 때 트래픽이 적은 리소스에 대한 가시성을 유지하는 데 도움이 돼요.

참고: 희귀 샘플러는 Agent 수준에서 로컬 트레이스를 캡처해요. 트레이스가 분산되어 있으면 완전한 트레이스가 Datadog로 보내진다는 보장은 없어요.

Datadog Agent 7.42.0 이상

Agent 버전 7.42.0 이상을 사용하면 희귀 샘플링을 원격으로 구성할 수 있어요. 문서에 따라 Agent에서 원격 구성을 활성화하세요. 원격 구성을 사용하면 Datadog Agent를 재시작하지 않고 파라미터 값을 변경할 수 있어요.

Datadog Agent 6/7.41.0 이상

기본적으로 희귀 샘플러는 활성화되어 있지 않아요.

참고: 활성화되면 SDK 규칙이나 manual.drop 같은 커스텀 로직으로 드롭된 스팬은 이 샘플러에서 제외돼요.

희귀 샘플러를 구성하려면 Agent 기본 구성 파일(datadog.yaml)에서 apm_config.enable_rare_sampler 설정을 업데이트하거나 환경 변수 DD_APM_ENABLE_RARE_SAMPLER를 사용하세요:

@params apm_config.enable_rare_sampler - boolean - optional - default: false
@env DD_APM_ENABLE_RARE_SAMPLER - boolean - optional - default: false

SDK 규칙이나 manual.drop 같은 커스텀 로직으로 드롭된 스팬을 평가하려면 Trace Agent에서 DD_APM_FEATURES=error_rare_sample_tracer_drop으로 기능을 활성화하세요.

Datadog Agent 6/7.33 ~ 6/7.40.x

기본적으로 희귀 샘플러는 활성화되어 있어요.

참고: 활성화되면 SDK 규칙이나 manual.drop 같은 커스텀 로직으로 드롭된 스팬은 이 샘플러에서 제외돼요. 이 스팬을 이 로직에 포함하려면 Datadog Agent 6.41.0/7.41.0 이상으로 업그레이드하세요.

기본 희귀 샘플러 설정을 변경하려면 Agent 기본 구성 파일(datadog.yaml)에서 apm_config.disable_rare_sampler 설정을 업데이트하거나 환경 변수 DD_APM_DISABLE_RARE_SAMPLER를 사용하세요:

@params apm_config.disable_rare_sampler - boolean - optional - default: false
@env DD_APM_DISABLE_RARE_SAMPLER - boolean - optional - default: false

강제 유지 및 드롭 (Force keep and drop)

ingestion_reason: manual

헤드 기반 샘플링 메커니즘은 SDK 수준에서 덮어쓸 수 있어요. 예를 들어 중요 트랜잭션을 모니터링해야 한다면 관련 트레이스를 강제로 유지할 수 있어요. 반면 헬스 체크 같은 불필요하거나 반복적인 정보는 트레이스를 강제로 드롭할 수 있어요.

• 스팬에 Manual Keep을 설정해 해당 스팬과 모든 자식 스팬이 수집되도록 해요. 해당 스팬이 트레이스의 루트 스팬이 아니면 결과 트레이스가 UI에서 불완전하게 보일 수 있어요.
• 스팬에 Manual Drop을 설정해 어떤 자식 스팬도 수집되지 않도록 해요. Agent에서 오류 및 희귀 샘플러는 무시돼요.

Java

트레이스를 수동으로 유지하기:

import datadog.trace.api.DDTags;
import io.opentracing.Span;
import datadog.trace.api.Trace;
import io.opentracing.util.GlobalTracer;

public class MyClass {
    @Trace
    public static void myMethod() {
        // grab the active span out of the traced method
        Span span = GlobalTracer.get().activeSpan();
        // Always keep the trace
        span.setTag(DDTags.MANUAL_KEEP, true);
        // method impl follows
    }
}

트레이스를 수동으로 드롭하기:

import datadog.trace.api.DDTags;
import io.opentracing.Span;
import datadog.trace.api.Trace;
import io.opentracing.util.GlobalTracer;

public class MyClass {
    @Trace
    public static void myMethod() {
        // grab the active span out of the traced method
        Span span = GlobalTracer.get().activeSpan();
        // Always Drop the trace
        span.setTag(DDTags.MANUAL_DROP, true);
        // method impl follows
    }
}

Python

트레이스를 수동으로 유지하기:

from ddtrace import tracer
from ddtrace.constants import MANUAL_DROP_KEY, MANUAL_KEEP_KEY

@tracer.wrap()
def handler():
    span = tracer.current_span()
    # Always Keep the Trace
    span.set_tag(MANUAL_KEEP_KEY)
    # method impl follows

트레이스를 수동으로 드롭하기:

from ddtrace import tracer
from ddtrace.constants import MANUAL_DROP_KEY, MANUAL_KEEP_KEY

@tracer.wrap()
def handler():
    span = tracer.current_span()
    # Always Drop the Trace
    span.set_tag(MANUAL_DROP_KEY)
    # method impl follows

Ruby

트레이스를 수동으로 유지하기:

Datadog::Tracing.trace(name, options) do |span, trace|
  trace.keep! # Affects the active trace
  # Method implementation follows
end

트레이스를 수동으로 드롭하기:

Datadog::Tracing.trace(name, options) do |span, trace|
  trace.reject! # Affects the active trace
  # Method implementation follows
end

Go

참고: 이 문서는 모든 사용자에게 권장되는 Go 트레이서 v2를 사용해요. v1을 사용 중이라면 v2로 업그레이드하려면 마이그레이션 가이드를 참고하세요.

트레이스를 수동으로 유지하기:

package main

import (
    "log"
    "net/http"
    "github.com/DataDog/dd-trace-go/v2/ddtrace/ext" 
    "github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)

func handler(w http.ResponseWriter, r *http.Request) {
    // Create a span for a web request at the /posts URL.
    span := tracer.StartSpan("web.request", tracer.ResourceName("/posts"))
    defer span.Finish()

    // Always keep this trace:
    span.SetTag(ext.ManualKeep, true)
    //method impl follows

}

트레이스를 수동으로 드롭하기:

package main

import (
    "log"
    "net/http"

    "github.com/DataDog/dd-trace-go/v2/ddtrace/ext"
    "github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
)

func handler(w http.ResponseWriter, r *http.Request) {
    // Create a span for a web request at the /posts URL.
    span := tracer.StartSpan("web.request", tracer.ResourceName("/posts"))
    defer span.Finish()

    // Always drop this trace:
    span.SetTag(ext.ManualDrop, true)
    //method impl follows
}

Node.js

트레이스를 수동으로 유지하기:

const tracer = require('dd-trace')
const tags = require('dd-trace/ext/tags')

const span = tracer.startSpan('web.request')

// Always keep the trace
span.setTag(tags.MANUAL_KEEP)
//method impl follows

트레이스를 수동으로 드롭하기:

const tracer = require('dd-trace')
const tags = require('dd-trace/ext/tags')

const span = tracer.startSpan('web.request')

// Always drop the trace
span.setTag(tags.MANUAL_DROP)
//method impl follows

.NET

트레이스를 수동으로 유지하기:

using Datadog.Trace;

using(var scope = Tracer.Instance.StartActive("my-operation"))
{
    var span = scope.Span;

    // Always keep this trace
    span.SetTag(Datadog.Trace.Tags.ManualKeep, "true");
    //method impl follows
}

트레이스를 수동으로 드롭하기:

using Datadog.Trace;

using(var scope = Tracer.Instance.StartActive("my-operation"))
{
    var span = scope.Span;

    // Always drop this trace
    span.SetTag(Datadog.Trace.Tags.ManualDrop, "true");
    //method impl follows
}

PHP

트레이스를 수동으로 유지하기:

<?php
  $tracer = \DDTrace\GlobalTracer::get();
  $span = $tracer->getActiveSpan();

  if (null !== $span) {
    // Always keep this trace
    $span->setTag(\DDTrace\Tag::MANUAL_KEEP, true);
  }
?>

트레이스를 수동으로 드롭하기:

<?php
  $tracer = \DDTrace\GlobalTracer::get();
  $span = $tracer->getActiveSpan();

  if (null !== $span) {
    // Always drop this trace
    $span->setTag(\DDTrace\Tag::MANUAL_DROP, true);
  }
?>

C++

트레이스를 수동으로 유지하기:

...
#include <datadog/tags.h>
#include <datadog/trace_segment.h>
#include <datadog/sampling_priority.h>
...

dd::SpanConfig span_cfg;
span_cfg.resource = "operation_name";

auto span = tracer.create_span(span_cfg);
// Always keep this trace
span.trace_segment().override_sampling_priority(int(dd::SamplingPriority::USER_KEEP));
//method impl follows

트레이스를 수동으로 드롭하기:

...
#include <datadog/tags.h>
#include <datadog/trace_segment.h>
#include <datadog/sampling_priority.h>
...

using namespace dd = datadog::tracing;

dd::SpanConfig span_cfg;
span_cfg.resource = "operation_name";

auto another_span = tracer.create_span(span_cfg);
// Always drop this trace
span.trace_segment().override_sampling_priority(int(dd::SamplingPriority::USER_DROP));
//method impl follows

Rust

참고: Rust SDK는 OpenTelemetry API를 사용하며 Datadog ManualKeep/ManualDrop 태그를 지원하지 않아요. Rust에서 트레이스를 강제 유지 또는 드롭하려면 커스텀 계측을 사용해 루트 스팬에 OpenTelemetry sampling.priority 속성을 설정하세요.

컨텍스트 전파 전에 Manual Keep을 설정하세요. 컨텍스트 전파 후에 설정하면 전체 트레이스가 서비스 전체에서 유지되지 않을 수 있어요. 이 결정은 트레이싱 클라이언트에서 내려지므로 트레이스는 여전히 샘플링 규칙에 따라 Agent나 서버에서 드롭될 수 있어요.

단일 스팬 (Single spans)

ingestion_reason: single_span

특정 스팬만 샘플링하고 전체 트레이스는 필요 없다면 SDK에서 단일 스팬의 샘플링 비율을 설정할 수 있어요.

예를 들어 특정 서비스를 모니터링하기 위해 스팬에서 메트릭을 만들고 있다면, 서비스를 흐르는 모든 요청에 대해 트레이스 100%를 수집하지 않으면서 메트릭이 애플리케이션 트래픽 100%에 기반하도록 스팬 샘플링 규칙을 구성할 수 있어요.

이 기능은 Datadog Agent v7.40.0+에서 사용할 수 있어요.

참고: 단일 스팬 샘플링 규칙은 헤드 기반 샘플링이 유지한 스팬을 드롭하는 데는 사용할 수 없어요. 헤드 기반 샘플링이 드롭한 추가 스팬을 유지하는 데만 사용할 수 있어요.

Java

SDK 버전 1.7.0부터 Java 애플리케이션에서 DD_SPAN_SAMPLING_RULES 환경 변수로 서비스별·오퍼레이션 이름별 스팬 샘플링 규칙을 설정하세요.

예를 들어 my-service 서비스의 http.request 오퍼레이션에서 초당 최대 50개 스팬까지 스팬 100%를 수집하려면:

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

샘플링 제어에 대한 자세한 내용은 Java SDK 문서를 참고하세요.

Python

버전 v1.4.0부터 Python 애플리케이션에서 DD_SPAN_SAMPLING_RULES 환경 변수로 서비스별·오퍼레이션 이름별 스팬 샘플링 규칙을 설정하세요.

예를 들어 my-service 서비스의 http.request 오퍼레이션에서 초당 최대 50개 스팬까지 스팬 100%를 수집하려면:

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

샘플링 제어에 대한 자세한 내용은 Python SDK 문서를 참고하세요.

Ruby

버전 v1.5.0부터 Ruby 애플리케이션에서 DD_SPAN_SAMPLING_RULES 환경 변수로 서비스별·오퍼레이션 이름별 스팬 샘플링 규칙을 설정하세요.

예를 들어 my-service 서비스의 http.request 오퍼레이션에서 초당 최대 50개 스팬까지 스팬 100%를 수집하려면:

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

샘플링 제어에 대한 자세한 내용은 Ruby SDK 문서를 참고하세요.

Go

버전 v1.41.0부터 Go 애플리케이션에서 DD_SPAN_SAMPLING_RULES 환경 변수로 서비스별·오퍼레이션 이름별 스팬 샘플링 규칙을 설정하세요.

예를 들어 my-service 서비스의 http.request 오퍼레이션에서 초당 최대 50개 스팬까지 스팬 100%를 수집하려면:

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

버전 v1.60.0부터 Go 애플리케이션에서 DD_SPAN_SAMPLING_RULES 환경 변수로 리소스별·태그별 스팬 샘플링 규칙을 설정하세요.

예를 들어 POST /api/create_issue 리소스에서 값이 high인 priority 태그에 대해 스팬 100%를 수집하려면:

@env DD_SPAN_SAMPLING_RULES=[{"resource": "POST /api/create_issue", "tags": { "priority":"high" }, "sample_rate":1.0}]

샘플링 제어에 대한 자세한 내용은 Go SDK 문서를 참고하세요.

Node.js

Node.js 애플리케이션에서 DD_SPAN_SAMPLING_RULES 환경 변수로 서비스별·오퍼레이션 이름별 스팬 샘플링 규칙을 설정하세요.

예를 들어 my-service 서비스의 http.request 오퍼레이션에서 초당 최대 50개 스팬까지 스팬 100%를 수집하려면:

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

샘플링 제어에 대한 자세한 내용은 Node.js SDK 문서를 참고하세요.

PHP

버전 v0.77.0부터 PHP 애플리케이션에서 DD_SPAN_SAMPLING_RULES 환경 변수로 서비스별·오퍼레이션 이름별 스팬 샘플링 규칙을 설정하세요.

예를 들어 my-service 서비스의 http.request 오퍼레이션에서 초당 최대 50개 스팬까지 스팬 100%를 수집하려면:

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

샘플링 제어에 대한 자세한 내용은 PHP SDK 문서를 참고하세요.

C++

버전 v0.1.0부터 C++ 애플리케이션에서 DD_SPAN_SAMPLING_RULES 환경 변수로 서비스별·오퍼레이션 이름별 스팬 샘플링 규칙을 설정하세요.

예를 들어 my-service 서비스의 http.request 오퍼레이션에서 초당 최대 50개 스팬까지 스팬 100%를 수집하려면:

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

Rust

Rust 애플리케이션에서 DD_SPAN_SAMPLING_RULES 환경 변수로 서비스별·오퍼레이션 이름별 스팬 샘플링 규칙을 설정하세요.

예를 들어 my-service 서비스의 http.request 오퍼레이션에서 초당 최대 50개 스팬까지 스팬 100%를 수집하려면:

@env DD_SPAN_SAMPLING_RULES=[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]

.NET

버전 v2.18.0부터 .NET 애플리케이션에서 DD_SPAN_SAMPLING_RULES 환경 변수로 서비스별·오퍼레이션 이름별 스팬 샘플링 규칙을 설정하세요.

예를 들어 my-service 서비스의 http.request 오퍼레이션에서 초당 최대 50개 스팬까지 스팬 100%를 수집하려면:

#using powershell
$env:DD_SPAN_SAMPLING_RULES='[{"service": "my-service", "name": "http.request", "sample_rate":1.0, "max_per_second": 50}]'

#using JSON file   
{
    "DD_SPAN_SAMPLING_RULES": "[{\"service\": \"my-service\", \"name\": \"http.request\", \"sample_rate\": 1.0, \"max_per_second\": 50}]"
}

샘플링 제어에 대한 자세한 내용은 .NET SDK 문서를 참고하세요.

경고: 레거시 App Analytics 메커니즘은 완전히 지원 중단(deprecated)됐어요. 개별 스팬을 수집하려면 (위에 설명된) 단일 스팬 샘플링을, 완전한 트레이스를 수집하려면 헤드 기반 샘플링을 사용하세요.

제품 수집 스팬 (Product ingested spans)

RUM 트레이스 (RUM traces)

ingestion_reason:rum

백엔드 서비스가 계측되면 웹 또는 모바일 애플리케이션의 요청이 트레이스를 생성해요. Real User Monitoring과의 APM 인테그레이션은 웹·모바일 애플리케이션 요청을 해당 백엔드 트레이스에 연결하여 하나의 렌즈로 전체 프론트엔드·백엔드 데이터를 볼 수 있게 해 줘요.

RUM 브라우저 SDK 버전 4.30.0부터 traceSampleRate 초기화 파라미터를 구성해 수집 볼륨을 제어하고 백엔드 트레이스의 일부를 유지할 수 있어요. traceSampleRate를 0과 100 사이의 숫자로 설정하세요. traceSampleRate 값이 설정되지 않으면 브라우저 요청에서 오는 트레이스 기본값 100%가 Datadog로 보내져요.

다른 SDK에서도 트레이스 샘플링 비율을 제어할 수 있어요:

SDK	파라미터	최소 버전
Browser	traceSampleRate	v4.30.0
iOS	tracingSamplingRate	1.11.0 샘플링 비율은 1.13.0부터 Ingestion Control 페이지에 보고됨
Android	traceSampleRate	1.13.0 샘플링 비율은 1.15.0부터 Ingestion Control 페이지에 보고됨
Flutter	tracingSamplingRate	1.0.0
React Native	tracingSamplingRate	1.0.0 샘플링 비율은 1.2.0부터 Ingestion Control 페이지에 보고됨

신디틱 트레이스 (Synthetic traces)

ingestion_reason:synthetics 및 ingestion_reason:synthetics-browser

백엔드 서비스가 계측되면 HTTP 및 브라우저 테스트가 트레이스를 생성해요. Synthetic Testing과의 APM 인테그레이션은 신디틱 테스트를 해당 백엔드 트레이스에 연결해요. 실패한 테스트 실행에서 해당 테스트 실행이 생성한 트레이스를 살펴 문제의 근본 원인으로 이동할 수 있어요.

기본적으로 신디틱 HTTP 및 브라우저 테스트의 100%가 백엔드 트레이스를 생성해요.

기타 제품 (Other products)

특정 Datadog 제품이 생성한 스팬에 기인하는 추가 수집 이유가 있어요:

제품	수집 이유	수집 메커니즘 설명
Serverless	lambda 및 xray	Datadog SDK 또는 AWS X-Ray 인테그레이션으로 트레이싱된 Serverless 애플리케이션에서 받은 트레이스
App and API Protection	appsec	Datadog SDK에서 수집되어 AAP가 위협으로 플래그한 트레이스
Data Observability: Jobs Monitoring	data_jobs	Datadog Java Tracer Spark 인테그레이션 또는 Databricks 인테그레이션에서 수집된 트레이스

OpenTelemetry의 수집 메커니즘 (Ingestion mechanisms in OpenTelemetry)

ingestion_reason:otel

OpenTelemetry SDK 설정(OpenTelemetry Collector 또는 Datadog Agent 사용)에 따라 수집 샘플링을 제어하는 여러 방법이 있어요. 다양한 OpenTelemetry 설정에서 OpenTelemetry SDK, OpenTelemetry Collector, Datadog Agent 수준에서 샘플링에 사용 가능한 옵션에 대한 자세한 내용은 OpenTelemetry와 수집 샘플링을 참고하세요.

더 알아보기 (Learn more)

• 수집 제어 (Ingestion Controls)
• 트레이스 보존 (Trace Retention)
• 사용량 메트릭 (Usage Metrics)