opentelemetry c++ sdk 当前（2024 年中）仍为 beta 阶段，api 不稳定、自动埋点与上下文传播能力弱于 go/java，不建议用于金融级交易链路；需手动管理 span 生命周期、跨线程 context 传递及 otlp 配置，且 attribute 仅支持基础类型。
确认 OpenTelemetry C++ SDK 是否满足生产要求
OpenTelemetry C++ SDK 目前（截至 2024 年中）仍标记为 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。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 避免在类成员函数中隐式访问全局 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<opentelemetry::sdk::trace::SpanExporter>(
new opentelemetry::exporter::trace::OtlpHttpExporter{});
auto processor = std::unique_ptr<opentelemetry::sdk::trace::SpanProcessor>(
new opentelemetry::sdk::trace::SimpleSpanProcessor(std::move(exporter)));
auto provider = std::shared_ptr<opentelemetry::sdk::trace::TracerProvider>(
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> 会静默失败。只能逐个设为 string、int、bool 或 double。
