如何使用OpenTelemetry为c++微服务添加分布式追踪？ (可观测性)_技术教程

OpenTelemetry C++ SDK 当前（2025 年中）仍为 beta 阶段，API 不稳定、自动埋点与上下文传播能力弱于 Go/Java，不建议用于金融级交易链路；需手动管理 span 生命周期、跨线程 context 传递及 OTLP 配置，且 attribute 仅支持基础类型。

确认 OpenTelemetry C++ SDK 是否满足生产要求

OpenTelemetry C++ SDK 目前（截至 2025 年中）仍标记为 beta，API 不保证向后兼容，且部分功能（如自动 instrument HTTP 客户端/服务器、进程内上下文传播的默认行为）不如 Go/Java 成熟。如果你的微服务对 tracing 稳定性、低延迟或采样精度有硬性要求，需谨慎评估——它适合灰度验证或非核心链路，不建议直接用于金融级交易链路。

关键判断点：

是否依赖 opentelemetry-cpp-contrib 中的第三方库插件（如 libcurl、grpc 自动埋点）？这些插件多数未进主干，需自行编译并承担维护成本
SDK 默认使用 std::shared_ptr 管理 span，高频创建 span 时可能触发锁竞争，压测下可观测到 otel_tracer_start_span 耗时抖动
传播头默认只支持 traceparent（W3C），若上下游混用 Zipkin B3 或 Jaeger Thrift，需手动注册自定义 TextMapPropagator

手动初始化 tracer 并注入全局上下文

C++ 没有语言级 context propagation（不像 Python 的 contextvars 或 Go 的 context.Context），必须显式传递 opentelemetry::trace::Scope 或使用线程局部存储（TLS）模拟。最稳妥的方式是：在每个请求入口（如 REST handler 或 gRPC service method）创建 root span，并将其绑定到当前线程的 TLS slot。

实操建议：

避免在类成员函数中隐式访问全局 tracer——不同线程可能拿到不同 tracer 实例，导致 span 丢失
使用 opentelemetry::trace::TracerProvider::GetTracer("your-service") 获取 tracer，不要缓存返回值，因 provider 可能被热替换
务必调用 span->End()，C++ 不支持 defer；漏掉会导致 span 永久 pending，内存泄漏且后端收不到完整 trace

#include "opentelemetry/sdk/trace/simple_processor.h"
#include "opentelemetry/sdk/trace/exporter.h"
#include "opentelemetry/sdk/trace/tracer_provider.h"
#include "opentelemetry/trace/provider.h"

auto exporter = std::unique_ptr(
    new opentelemetry::exporter::trace::OtlpHttpExporter{});
auto processor = std::unique_ptr(
    new opentelemetry::sdk::trace::SimpleSpanProcessor(std::move(exporter)));
auto provider = std::shared_ptr(
    new opentelemetry::sdk::trace::TracerProvider(std::move(processor)));
opentelemetry::trace::Provider::SetGlobalTracerProvider(provider);

// 在请求处理函数中：
auto tracer = opentelemetry::trace::Provider::GetGlobalTracerProvider()->GetTracer("my-service");
auto span = tracer->StartSpan("handle_request");
opentelemetry::trace::Scope scope(span); // 绑定到当前线程 TLS
// ... 业务逻辑 ...
span->End(); // 必须显式调用

跨线程与异步操作的 span 传递

当服务内部使用线程池（如 std::async、boost::asio::post）或回调模型时，父 span 不会自动继承。OpenTelemetry C++ 不提供类似 Java 的 Context.wrap(Runnable) 工具，必须手动捕获并重装 context。

常见错误现象：

子线程中调用 tracer->StartSpan() 生成孤立 span，无 parent_id，trace graph 断开
gRPC 异步完成回调里 span 显示为 root，实际应是 child

正确做法：

在派发前调用 opentelemetry::context::Context::GetCurrent() 获取当前 context
将 context 作为参数传入 lambda 或 functor（注意生命周期，避免悬垂引用）
在子线程入口处调用 opentelemetry::context::Context::SetCurrent(ctx)

示例（线程池任务）：

auto current_ctx = opentelemetry::context::Context::GetCurrent();
std::thread([current_ctx] {
  opentelemetry::context::Context::SetCurrent(current_ctx);
  auto tracer = opentelemetry::trace::Provider::GetGlobalTracerProvider()->GetTracer("my-service");
  auto span = tracer->StartSpan("background_task");
  opentelemetry::trace::Scope scope(span);
  // ... work ...
  span->End();
}).detach();

对接 OTLP 后端并验证 trace 数据完整性

OpenTelemetry C++ SDK 默认通过 HTTP POST 发送 OTLP/HTTP（非 gRPC），endpoint 必须以 /v1/traces 结尾，且需确保服务可访问该地址。常见失败原因不是代码问题，而是网络或协议细节：

环境变量 OTEL_EXPORTER_OTLP_ENDPOINT 若不含协议（如写成 localhost:4318），SDK 默认拼 http://，但多数 collector（如 Grafana Tempo、Jaeger）默认只监听 https:// 或需显式启用 HTTP
若 collector 启用了 TLS 认证，需额外配置 OTEL_EXPORTER_OTLP_CERTIFICATE 和证书路径，否则连接直接拒绝，日志仅显示 “connection refused”
Span 的 status_code 默认为 Unset，不会自动设为 Error 即使抛了异常——必须手动调用 span->SetStatus(opentelemetry::trace::StatusCode::kError, "msg")

验证 trace 是否发出的最快方式：用 tcpdump 抓包看是否有 POST /v1/traces 请求；再 curl collector 的 health check 接口（如 curl http://localhost:14269/metrics | grep otel_）确认接收计数上涨。

容易被忽略的是 span attribute 的类型限制：C++ SDK 不支持嵌套 map 或 vector 作为 attribute 值，span->SetAttribute("tags", std::vector<:string>{"a","b"}) 会静默失败。只能逐个设为 string、int、bool 或 double。