Skip to content

Trace Configuration

The Windows SDK Trace injects distributed tracing headers into HTTP requests and associates the generated trace_id and span_id with the corresponding RUM Resource. The SDK does not create or upload standalone APM spans.

Trace Initialization Configuration

TrueWatchSdk.Init(new TrueWatchConfig
{
    DatawayUrl = "https://openway.truewatch.com",
    ClientToken = "<client-token>",
    RumAppId = "<rum-app-id>",
    Trace = new TraceConfig
    {
        EnableAutoTrace = true,
        EnableLinkRumData = true,
        SamplingRate = 100, // Supported as of 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;
}

truewatch_trace_config_v2 trace;
truewatch_trace_config_v2_init(&trace);
trace.enable_auto_trace = 1;
trace.enable_link_rum_data = 1;
trace.sampling_rate = 100.0f; // Supported as of vcpkg 0.1.0-alpha.9
trace.trace_type = TRUEWATCH_TRACE_TRACEPARENT;
trace.should_trace = should_trace;

if (!truewatch_trace_configure_v2(rum, &trace)) {
    // The configuration is invalid; Trace is not enabled.
}

Configuration Parameters

Description .NET / C# Native C/C++ Default
Auto-generate trace context EnableAutoTrace enable_auto_trace false / 0
Link RUM Resource EnableLinkRumData enable_link_rum_data false / 0
Sampling rate SamplingRate (as of NuGet 0.1.0-alpha.8) sampling_rate (as of vcpkg 0.1.0-alpha.9) 100
Sampling rate (legacy, 0–1; use SamplingRate / v2 sampling_rate instead) SampleRate (deprecated) legacy struct sample_rate (deprecated) 1
Propagation format TraceType trace_type DDTrace
Target filtering ShouldTrace should_trace Empty
Custom context ContextProvider context_provider Empty
Callback context Closure user_data Empty

The Trace sampling rate is a float percentage in the range 0–100, with decimal values supported. It only controls the sampled flag in the propagation protocol and does not replace the RUM Session sampling rate.

Supported Propagation Formats

C# Native C/C++ Header
TraceType.DdTrace TRUEWATCH_TRACE_DDTRACE x-datadog-*
TraceType.ZipkinMultiHeader TRUEWATCH_TRACE_ZIPKIN_MULTI_HEADER X-B3-TraceId, X-B3-SpanId, X-B3-Sampled
TraceType.ZipkinSingleHeader TRUEWATCH_TRACE_ZIPKIN_SINGLE_HEADER b3
TraceType.TraceParent TRUEWATCH_TRACE_TRACEPARENT traceparent
TraceType.SkyWalking TRUEWATCH_TRACE_SKYWALKING sw8
TraceType.Jaeger TRUEWATCH_TRACE_JAEGER uber-trace-id

The server or Agent must support the selected propagation format.

Tracer Network Tracing

After enabling HttpClient automatic instrumentation, the SDK applies the Trace configuration before sending the request:

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

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

To control the Handler explicitly, use:

using var http = new HttpClient(
    TrueWatchSdk.CreateHttpMessageHandler(new HttpClientHandler()));

C++ WinHTTP applications use truewatch_rum_winhttp.hpp. The adapter generates headers, completes the request, and writes the same IDs to the RUM Resource:

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

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

Asynchronous WinHTTP requires WinHttpRequestMode::asynchronous; keep the object alive until the completion callback and call complete_from_response() once the headers are available.

Custom Trace Context

ContextProvider can return custom headers and associated identifiers:

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

If the provider returns null or invalid headers, the SDK skips Trace for this request without interrupting the host request.

For non-WinHTTP network libraries, generate the context and write the headers yourself:

truewatch_trace_context context;
truewatch_trace_context_init(&context);

if (truewatch_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;
        // Write the headers using the current network library.
    }
}

When capturing the Resource manually, pass context.trace_id and context.span_id to truewatch_rum_stop_resource_ext(). Associate them only when context.link_rum_data != 0.

Security Boundary

Restrict Trace Header target addresses

When no target filtering is configured, all absolute URLs entering the automatic Trace collection boundary may receive Trace Headers. In production, set an explicit allowlist based on protocol, hostname, and port to avoid sending trace context to third parties.

Native configuration copies strings but retains the callback and user_data. They must remain valid until reconfiguration or truewatch_sdk_shutdown(). Callbacks may be invoked concurrently by multiple request threads; do not let C++ exceptions cross the C ABI.