コンテンツにスキップ

Trace 設定

Windows SDK の Trace は、HTTP リクエストに分散型トレーシングの Header を注入し、生成された 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,
        SamplingRate = 100, // NuGet 0.1.0-alpha.8 からサポート
        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_v2 trace;
{{ windows_sdk_id }}_trace_config_v2_init(&trace);
trace.enable_auto_trace = 1;
trace.enable_link_rum_data = 1;
trace.sampling_rate = 100.0f; // vcpkg 0.1.0-alpha.9 からサポート
trace.trace_type = {{ windows_sdk_constant }}_TRACE_TRACEPARENT;
trace.should_trace = should_trace;

if (!{{ windows_sdk_id }}_trace_configure_v2(rum, &trace)) {
    // 設定が無効なため、Trace は有効になりません。
}

設定パラメータ

意味 .NET / C# Native C/C++ デフォルト値
Trace コンテキストの自動生成 EnableAutoTrace enable_auto_trace false / 0
RUM Resource への関連付け EnableLinkRumData enable_link_rum_data false / 0
サンプリングレート SamplingRate(NuGet 0.1.0-alpha.8 から) sampling_rate(vcpkg 0.1.0-alpha.9 から) 100
サンプリングレート(旧、0~1。SamplingRate / v2 の sampling_rate を使用) SampleRate(非推奨) 旧構造の sample_rate(非推奨) 1
伝搬フォーマット TraceType trace_type DDTrace
ターゲットフィルタリング ShouldTrace should_trace 空
カスタムコンテキスト ContextProvider context_provider 空
コールバックコンテキスト クロージャ user_data 空

Trace のサンプリングレートは float のパーセント値で、範囲は 0~100 であり、小数にも対応しています。このサンプリングレートは伝搬プロトコルの 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 が送信される可能性があります。本番環境では、プロトコル、ホスト名、ポートによる明確なホワイトリストを設定し、トレースコンテキストを第三者に送信しないようにしてください。

Native 設定は文字列をコピーしますが、コールバックと user_data は保持されます。これらは再設定または {{ windows_sdk_id }}_sdk_shutdown() まで有効である必要があります。コールバックは複数のリクエストスレッドから並行して呼び出される可能性があるため、C++ 例外が C ABI を越えないようにしてください。

フィードバック

このページは役に立ちましたか?