콘텐츠로 이동

Trace 구성

Windows SDK의 Trace는 HTTP 요청에 분산 추적 헤더를 주입하고 생성된 trace_id, span_id를 해당 RUM Resource에 연결합니다. SDK는 별도의 APM Span을 생성하거나 업로드하지 않습니다.

Trace 초기화 구성

{{ windows_sdk_name }}Sdk.Init(new {{ windows_sdk_name }}Config
{
    DatawayUrl = "https://openway.guance.com",
    ClientToken = "<client-token>",
    RumAppId = "<rum-app-id>",
    Trace = new TraceConfig
    {
        EnableAutoTrace = true,
        EnableLinkRumData = true,
        SampleRate = 1.0,
        TraceType = TraceType.TraceParent,
        ShouldTrace = uri =>
            uri.Scheme == Uri.UriSchemeHttps &&
            uri.Host == "api.example.com"
    }
});

#include <string>

static int should_trace(const char* url, const char*, void*)
{
    const std::string value = url == nullptr ? "" : url;
    return value == "https://api.example.com" ||
        value.rfind("https://api.example.com/", 0) == 0;
}

{{ windows_sdk_id }}_trace_config trace;
{{ windows_sdk_id }}_trace_config_init(&trace);
trace.enable_auto_trace = 1;
trace.enable_link_rum_data = 1;
trace.sample_rate = 1.0;
trace.trace_type = {{ windows_sdk_constant }}_TRACE_TRACEPARENT;
trace.should_trace = should_trace;

if (!{{ windows_sdk_id }}_trace_configure(rum, &trace)) {
    // 구성이 잘못되어 Trace가 활성화되지 않았습니다.
}

구성 매개변수

의미 .NET / C# Native C/C++ 기본값
Trace 컨텍스트 자동 생성 EnableAutoTrace enable_auto_trace false / 0
RUM Resource 연결 EnableLinkRumData enable_link_rum_data false / 0
전파 샘플링 비율 SampleRate sample_rate 1.0
전파 형식 TraceType trace_type DDTrace
대상 필터링 ShouldTrace should_trace 없음
사용자 지정 컨텍스트 ContextProvider context_provider 없음
콜백 컨텍스트 클로저 user_data 없음

Trace 샘플링 비율은 전파 프로토콜의 sampled 표시만 제어하며 RUM Session 샘플링 비율을 대체하지 않습니다.

지원되는 전파 형식

C# Native C/C++ Header
TraceType.DdTrace {{ windows_sdk_constant }}_TRACE_DDTRACE x-datadog-*
TraceType.ZipkinMultiHeader {{ windows_sdk_constant }}_TRACE_ZIPKIN_MULTI_HEADER X-B3-TraceId, X-B3-SpanId, X-B3-Sampled
TraceType.ZipkinSingleHeader {{ windows_sdk_constant }}_TRACE_ZIPKIN_SINGLE_HEADER b3
TraceType.TraceParent {{ windows_sdk_constant }}_TRACE_TRACEPARENT traceparent
TraceType.SkyWalking {{ windows_sdk_constant }}_TRACE_SKYWALKING sw8
TraceType.Jaeger {{ windows_sdk_constant }}_TRACE_JAEGER uber-trace-id

서버 또는 Agent가 선택한 전파 형식을 지원해야 합니다.

Tracer 네트워크 분산 추적

HttpClient 자동 수집을 활성화하면 SDK는 요청 전송 전에 Trace 구성을 적용합니다.

{{ windows_sdk_name }}Sdk.EnableAutomaticInstrumentation(new AutomaticInstrumentationOptions
{
    EnableHttpClient = true
});

using var http = new HttpClient();
await http.GetAsync("https://api.example.com/items");

Handler를 명시적으로 제어해야 하는 경우 다음을 사용합니다.

using var http = new HttpClient(
    {{ windows_sdk_name }}Sdk.CreateHttpMessageHandler(new HttpClientHandler()));

C++ WinHTTP 애플리케이션은 {{ windows_sdk_id }}_rum_winhttp.hpp를 사용합니다. 어댑터가 Header를 생성하고 요청을 완료한 뒤 동일한 ID를 RUM Resource에 기록합니다.

{{ windows_sdk_id }}::rum::WinHttpResource resource(
    rum,
    request,
    "https://api.example.com/items",
    "GET");

if (resource.send()) {
    resource.receive();
}

비동기 WinHTTP에서는 WinHttpRequestMode::asynchronous를 사용해야 하며, 종료 콜백까지 객체를 유지하고 Header를 사용할 수 있게 된 후 complete_from_response()를 호출합니다.

사용자 지정 Trace 컨텍스트

ContextProvider는 사용자 지정 Header와 연결 식별자를 반환할 수 있습니다.

ContextProvider = request => new TraceContext(
    new Dictionary<string, string>
    {
        ["traceparent"] = CreateTraceParent()
    },
    traceId: currentTraceId,
    spanId: currentSpanId)

Provider가 null 또는 잘못된 Header를 반환하면 SDK는 이번 Trace를 건너뛰며 호스트 요청을 중단하지 않습니다.

WinHTTP가 아닌 네트워크 라이브러리는 컨텍스트를 생성하고 직접 Header를 작성할 수 있습니다.

{{ windows_sdk_id }}_trace_context context;
{{ windows_sdk_id }}_trace_context_init(&context);

if ({{ windows_sdk_id }}_trace_create_context(
        rum,
        "https://api.example.com/items",
        "GET",
        &context)) {
    for (uint32_t index = 0; index < context.header_count; ++index) {
        const char* name = context.headers[index].name;
        const char* value = context.headers[index].value;
        // 현재 네트워크 라이브러리를 사용하여 Header를 작성합니다.
    }
}

Resource를 직접 수집할 때는 context.trace_id와 context.span_id를 {{ windows_sdk_id }}_rum_stop_resource_ext()에 전달합니다. context.link_rum_data != 0인 경우에만 연결해야 합니다.

보안 경계

Trace Header 대상 주소 제한

대상 필터링을 구성하지 않으면 자동 Trace 수집 경계에 들어오는 모든 절대 URL이 Trace Header를 받을 수 있습니다. 프로덕션 환경에서는 프로토콜, 호스트명, 포트를 기준으로 명시적인 허용 목록을 설정하여 트레이스 컨텍스트가 제3자에게 전송되지 않도록 해야 합니다.

Native 구성은 문자열을 복사하지만 콜백과 user_data는 유지합니다. 이들은 재구성하거나 {{ windows_sdk_id }}_sdk_shutdown()을 호출하기 전까지 유효해야 합니다. 콜백은 여러 요청 스레드에서 동시에 호출될 수 있으므로 C++ 예외가 C ABI를 넘지 않도록 하세요.

문서 평가

이 페이지가 도움이 되었나요?