Trace 配置¶
Windows SDK 的 Trace 用于向 HTTP 请求注入分布式链路 Header，并把生成的 trace_id、span_id 关联到对应 RUM Resource。SDK 不创建或上传独立 APM Span。
初始化 Trace¶
RumSdk.Init(new RumConfig
{
DatawayUrl = "https://openway.guance.com",
ClientToken = "<client-token>",
RumAppId = "<rum-app-id>",
Trace = new RumTraceConfig
{
EnableAutoTrace = true,
EnableLinkRumData = true,
SampleRate = 1.0,
TraceType = RumTraceType.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_rum_trace_config trace;
guance_rum_trace_config_init(&trace);
trace.enable_auto_trace = 1;
trace.enable_link_rum_data = 1;
trace.sample_rate = 1.0;
trace.trace_type = GUANCE_RUM_TRACE_TRACEPARENT;
trace.should_trace = should_trace;
if (!guance_rum_configure_trace(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 |
|---|---|---|
RumTraceType.DdTrace |
GUANCE_RUM_TRACE_DDTRACE |
x-datadog-* |
RumTraceType.ZipkinMultiHeader |
GUANCE_RUM_TRACE_ZIPKIN_MULTI_HEADER |
X-B3-TraceId、X-B3-SpanId、X-B3-Sampled |
RumTraceType.ZipkinSingleHeader |
GUANCE_RUM_TRACE_ZIPKIN_SINGLE_HEADER |
b3 |
RumTraceType.TraceParent |
GUANCE_RUM_TRACE_TRACEPARENT |
traceparent |
RumTraceType.SkyWalking |
GUANCE_RUM_TRACE_SKYWALKING |
sw8 |
RumTraceType.Jaeger |
GUANCE_RUM_TRACE_JAEGER |
uber-trace-id |
服务端或 Agent 必须支持选择的传播格式。
自动 HTTP Trace¶
开启 HttpClient 自动采集后，SDK 会在请求发送前应用 Trace 配置：
RumSdk.EnableAutomaticInstrumentation(new AutomaticInstrumentationOptions
{
EnableHttpClient = true
});
using var http = new HttpClient();
await http.GetAsync("https://api.example.com/items");
需要显式控制 Handler 时使用：
C++ WinHTTP 应用使用 guance_rum_winhttp.hpp。适配器会生成 Header、完成请求并把相同 ID 写入 RUM Resource：
guance::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 RumTraceContext(
new Dictionary<string, string>
{
["traceparent"] = CreateTraceParent()
},
traceId: currentTraceId,
spanId: currentSpanId)
Provider 返回 null 或无效 Header 时，SDK 跳过本次 Trace，不中断宿主请求。
非 WinHTTP 网络库可以生成上下文并自行写入 Header：
guance_rum_trace_context context;
guance_rum_trace_context_init(&context);
if (guance_rum_create_trace_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 传给 guance_rum_stop_resource_ext()。只有 context.link_rum_data != 0 时才应关联。
安全边界¶
限制 Trace Header 的目标地址
未配置目标过滤时，所有进入自动 Trace 采集边界的绝对 URL 都可能收到 Trace Header。生产环境应按协议、主机名和端口设置明确白名单，避免把链路上下文发送给第三方。
Native 配置会复制字符串，但保留回调和 user_data。它们必须在重新配置或 guance_rum_shutdown() 前保持有效；回调可能由多个请求线程并发调用，不要让 C++ 异常跨越 C ABI。