Skip to content

Trace Configuration

The Windows SDK Trace injects distributed tracing headers into HTTP requests and correlates 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

GuanceSdk.Init(new GuanceConfig
{
    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;
}

guance_trace_config trace;
guance_trace_config_init(&trace);
trace.enable_auto_trace = 1;
trace.enable_link_rum_data = 1;
trace.sample_rate = 1.0;
trace.trace_type = GUANCE_TRACE_TRACEPARENT;
trace.should_trace = should_trace;

if (!guance_trace_configure(rum, &trace)) {
    // Invalid configuration; Trace is not enabled.
}

Configuration Parameters

Description .NET / C# Native C/C++ Default
Auto-generate Trace context EnableAutoTrace enable_auto_trace false / 0
Correlate RUM Resource EnableLinkRumData enable_link_rum_data false / 0
Propagation sample rate SampleRate sample_rate 1.0
Propagation format TraceType trace_type DDTrace
Target filtering ShouldTrace should_trace None
Custom context ContextProvider context_provider None
Callback context Closure user_data None

The Trace sample rate only controls the sampled flag in the propagation protocol and does not replace the RUM Session sample rate.

Supported Propagation Formats

C# Native C/C++ Header
TraceType.DdTrace GUANCE_TRACE_DDTRACE x-datadog-*
TraceType.ZipkinMultiHeader GUANCE_TRACE_ZIPKIN_MULTI_HEADER X-B3-TraceId, X-B3-SpanId, X-B3-Sampled
TraceType.ZipkinSingleHeader GUANCE_TRACE_ZIPKIN_SINGLE_HEADER b3
TraceType.TraceParent GUANCE_TRACE_TRACEPARENT traceparent
TraceType.SkyWalking GUANCE_TRACE_SKYWALKING sw8
TraceType.Jaeger GUANCE_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 the request is sent:

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

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

To explicitly control the handler, use:

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

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

guance::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 correlation 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 this Trace without interrupting the host request.

Network libraries other than WinHTTP can generate a context and write the headers themselves:

guance_trace_context context;
guance_trace_context_init(&context);

if (guance_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 headers using the current network library.
    }
}

When collecting the Resource yourself, pass context.trace_id and context.span_id to guance_rum_stop_resource_ext(). Only correlate when context.link_rum_data != 0.

Security Boundary

Restrict Trace Header Destinations

When no target filtering is configured, every absolute URL that enters the automatic Trace collection boundary may receive Trace headers. In production, set an explicit allowlist by protocol, hostname, and port to avoid sending trace context to third parties.

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

Feedback

Is this page helpful?