opentelemetry c++ sdk 不能直接开箱即用，需手动搭建骨架：必须显式注册exporter、管理tracerprovider与spanexporter长生命周期、调用forceflush()/shutdown()，且默认仅支持w3c traceparent传播，不兼容b3/jaeger需自定义propagator。
OpenTelemetry C++ SDK 能不能直接用？
不能直接开箱即用，得自己搭骨架。官方 opentelemetry-cpp 提供的是 SDK 核心（TracerProvider、Span、SpanContext），但不包含默认的 exporter、propagator 或自动 instrument，更没有现成的“客户端”封装。你得手动组合组件，尤其要注意生命周期管理——TracerProvider 和 SpanExporter 必须全局单例且长期存活，否则 Span 会静默丢弃。
常见错误现象：Span 创建了但后端收不到数据；日志里出现 Failed to export spans: No exporter configured；程序退出前没调用 ForceFlush() 导致最后一批 Span 丢失。
- 必须显式注册一个
SpanExporter（比如OtlpGrpcSpanExporter或OtlpHttpSpanExporter） -
TracerProvider初始化后，要用SetGlobalTracerProvider()绑定到全局上下文 - 进程退出前务必调用
provider->ForceFlush()和provider->Shutdown() - 避免在多线程频繁 new/delete
TracerProvider，它不是轻量对象
怎么把 trace_id 和 span_id 注入 HTTP 请求头？
靠 TextMapPropagator，但 C++ SDK 默认只提供 TraceContextPropagator（W3C Trace Context 标准），不支持 B3 或 Jaeger 风格。如果你的后端（比如 Zipkin）只认 X-B3-TraceId，就得自己实现或找社区版 B3Propagator。
使用场景：服务 A 调用服务 B 的 HTTP 接口时，需把当前 Span 的上下文写入请求头，让 B 能续接链路。
- 注入前先获取当前上下文：
auto current_ctx = opentelemetry::context::RuntimeContext::GetCurrent(); - 用
propagator->Inject()写入std::map<:string std::string></:string>或自定义 HTTP header 容器 - 注意：
TraceContextPropagator写的是traceparent和tracestate，不是X-B3-* - 若用 gRPC，优先走
GrpcClientInterceptor自动注入，比手撸 header 更可靠
如何让已有业务代码零侵入打点？
做不到完全零侵入，但能控制在最小改动：用 RAII 封装 Span 生命周期，配合宏或模板简化调用。不要在每个函数里手动调 StartSpan() 和 EndSpan()，容易漏掉 End() 导致内存泄漏或链路断裂。
性能影响明显：每次 StartSpan() 都涉及原子计数、时间戳采集、上下文切换，高频小 Span（如单条 DB 查询）建议批量聚合或采样过滤。
- 写一个
ScopedSpan类，在构造时StartSpan()，析构时自动End() - 用宏包装：比如
OTEL_AUTO_TRACE("db.query")展开为ScopedSpan _span("db.query"); - 关键路径加
SetAttribute()（如"db.statement"、"http.url"），但别塞大 JSON 字符串——SDK 默认有 128 字符长度限制 - 异步回调里打点要显式传入父
SpanContext，不能依赖线程局部存储（TLS）
为什么 Span 发不到 collector？常见连通性问题怎么查？
90% 是配置或网络层问题，和 SDK 逻辑关系不大。先确认 collector 地址、协议、TLS 设置是否匹配，再看 exporter 是否真正启动并注册成功。
错误信息典型例子：Failed to connect to endpoint: failed to connect to all addresses（gRPC）、HTTP status code 404（OTLP HTTP endpoint 路径错）、SSL handshake failed（证书不匹配）。
- 检查 collector 是否监听对应端口：
netstat -tuln | grep :4317（gRPC）或:4318（HTTP） - 用
curl -v http://localhost:4318/v1/traces测试 HTTP 连通性（需带空 POST body） - 启用 exporter 日志：
setenv("OTEL_CPP_LOG_LEVEL", "debug", 1)，看是否卡在连接阶段 - 若用 Docker，确认容器网络互通，别用
localhost——应填宿主机 IP 或 docker network 别名
最易被忽略的一点：OpenTelemetry C++ SDK 的 OTLP exporter 默认不启用 TLS，而很多 collector（如 Tempo、Jaeger）默认要求 TLS。要么关掉 collector 的 TLS 强制，要么在 exporter 配置里传入 ssl_target_name_override 和证书路径。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
