Trace 配置¶

本文用于承载 C++ SDK 的 Trace 初始化配置与链路追踪说明。

初始化 Trace¶

FTTraceConfig tc;
tc.setTraceType(TraceType::DDTRACE)
  .setEnableLinkRUMData(true);
sdk->initTraceWithConfig(tc);

字段	类型	必须	说明
`setSamplingRate`	float	否	采样率范围 `[0,1]`，`0` 表示不采集，`1` 表示全采集，默认值为 `1`
`setTraceType`	enum	否	默认为 `DDTrace`，支持 `Zipkin`、`Jaeger`、`DDTrace`、`Skywalking`（8.0+）、`TraceParent`（W3C）。如果接入 OpenTelemetry 选择对应链路类型时，请注意查阅支持类型及 agent 相关配置
`setEnableLinkRUMData`	bool	否	是否与 RUM 数据关联，默认为 `false`

生成 Trace Header¶

链路追踪通过生成 Trace Header，并将 Header 写入 HTTP 请求头来实现。

/**
 * 按配置生成 Trace Header
 *
 * @param resourceId 资源 ID
 * @param url 网络地址
 * @return trace 数据
 */
PropagationHeader generateTraceHeader(const std::string resourceId, const std::string url);

示例：

RestClient::init();
RestClient::Connection* conn = new RestClient::Connection(url);
std::string resId = "resource-id";

RestClient::HeaderFields headers;
headers["Accept"] = "application/json";

auto headerWithRes = sdk->generateTraceHeader(resId, url);
for (auto& hd : headerWithRes) {
    headers[hd.first] = hd.second;
}
conn->SetHeaders(headers);

RestClient::Response r = conn->get("/get");
RestClient::disable();

Windows 原生 SDK 自动 Trace¶

链接 guance_rum_native.dll 的 Windows C/C++ 应用可以为 WinHTTP 请求自动生成并注入 Trace Header，同时自动采集对应的 RUM Resource。开启 RUM 关联后，同一组 trace_id、span_id 会写入 Resource 数据，用于在 RUM 与 APM 之间关联跳转。

!!! note

SDK 注入的是所选链路协议对应的请求头，不会额外添加名为 `trace_id` 或 `span_id` 的 HTTP Header。`trace_id`、`span_id` 只在 `enable_link_rum_data = 1` 时写入 RUM Resource 字段。

配置¶

在 guance_rum_init 成功后配置 Trace。配置结构必须先调用 guance_rum_trace_config_init 初始化：

#include "guance_rum_winhttp.hpp"

#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 自动传播未启用。
}

字段	类型	默认值	说明
`enable_auto_trace`	int	`0`	是否为符合条件的 HTTP 请求自动生成 Trace 上下文
`enable_link_rum_data`	int	`0`	是否将生成的 `trace_id`、`span_id` 写入对应的 RUM Resource
`sample_rate`	double	`1.0`	Trace 采样决策比例，范围为 `[0,1]`；该值控制传播协议中的采样标记，不替代 RUM 会话采样配置
`trace_type`	`guance_rum_trace_type`	`GUANCE_RUM_TRACE_DDTRACE`	Trace Header 传播格式
`service_name`	string	RUM `service_name`	SkyWalking `sw8` 使用的服务名；其他内置传播格式忽略此字段
`should_trace`	callback	空	请求目标过滤回调；返回非 `0` 时才生成 Trace 上下文
`context_provider`	callback	空	自定义 Trace 上下文提供器；设置后替代 SDK 内置的 Header、Trace ID 和 Span ID 生成逻辑
`user_data`	void*	空	传递给两个回调的用户上下文

!!! warning

如果未设置 `should_trace`，所有传入自动 Trace API 的非空 URL 都可能收到 Trace Header。建议根据协议、主机名和端口构造明确的服务端白名单，避免将链路信息发送给第三方地址。

guance_rum_configure_trace 会复制字符串配置，但会保留回调与 user_data。它们必须在重新配置或 guance_rum_shutdown 前保持有效。回调为同步调用，并且可能由多个请求线程并发执行。

支持的传播格式¶

`guance_rum_trace_type`	协议	注入的 Header
`GUANCE_RUM_TRACE_DDTRACE`	Datadog	`x-datadog-origin`、`x-datadog-sampling-priority`、`x-datadog-parent-id`、`x-datadog-trace-id`
`GUANCE_RUM_TRACE_ZIPKIN_MULTI_HEADER`	Zipkin B3 Multi	`X-B3-TraceId`、`X-B3-SpanId`、`X-B3-Sampled`
`GUANCE_RUM_TRACE_ZIPKIN_SINGLE_HEADER`	Zipkin B3 Single	`b3`
`GUANCE_RUM_TRACE_TRACEPARENT`	W3C Trace Context	`traceparent`
`GUANCE_RUM_TRACE_SKYWALKING`	Apache SkyWalking	`sw8`
`GUANCE_RUM_TRACE_JAEGER`	Jaeger	`uber-trace-id`

服务端或 Agent 必须支持所选传播格式。默认格式为 GUANCE_RUM_TRACE_DDTRACE。

自动监测同步 WinHTTP 请求¶

先创建 WinHTTP Request Handle，再构造 guance::rum::WinHttpResource。构造函数会立即生成 Trace 上下文并将 Header 写入请求：

// request 是已通过 WinHttpOpenRequest 创建的 HINTERNET；target 为完整 URL。
guance::rum::WinHttpResource resource(
    rum,
    request,
    target.c_str(),
    "GET");

if (!resource.send()) {
    // 请求未发送。
}
if (!resource.receive()) {
    // 响应接收失败。
}

同步模式下，receive() 会读取响应状态、Content-Length 和 HTTP 版本，并结束 RUM Resource。WinHttpResource 不拥有 SDK Handle 或 WinHTTP Request Handle；两者必须比它存活更久。

异步 WinHTTP 请求需要传入 guance::rum::WinHttpRequestMode::asynchronous，保持 WinHttpResource 存活到终止回调，并在收到 WINHTTP_CALLBACK_STATUS_HEADERS_AVAILABLE 后调用 complete_from_response()。对该对象的回调访问需要由应用串行化。

手动获取 Trace 上下文¶

非 WinHTTP 网络库可以通过 C ABI 生成上下文，再将所有 Header 写入请求：

guance_rum_trace_context context{};
guance_rum_trace_context_init(&context);

if (guance_rum_create_trace_context(
        rum,
        "https://api.example.com/v1/user",
        "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;
        // 使用当前网络库将 name/value 写入请求 Header。
    }
}

如果自行采集 RUM Resource，请在结束 Resource 时将 context.trace_id、context.span_id 传入 guance_rum_stop_resource_ext。只有 context.link_rum_data != 0 时才应关联这两个字段。

需要延续已有链路或接入自定义协议时，可以设置 context_provider。SDK 会传入一个已初始化的 guance_rum_trace_context；回调填充 Header、Trace ID、Span ID 后返回非 0。最多支持 GUANCE_RUM_TRACE_MAX_HEADERS 个 Header。提供器返回 0 或提供无效数据时，SDK 会跳过本次 Trace 上下文生成，但不会中断宿主请求。不要让 C++ 异常跨越 C ABI 回调边界。