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:
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.