Kratos框架通过OpenTelemetry语义集成链路追踪,内置HTTP/gRPC中间件自动解析B3或W3C格式的Trace上下文并创建Span,支持Zipkin、Jaeger等后端;异步任务需手动注入context以避免断链,生产环境须配置采样率与限流避免性能问题。

Kratos 框架本身不直接实现链路追踪,而是通过 OpenTracing / OpenTelemetry 语义标准集成第三方追踪后端(如 Zipkin、Jaeger、OpenTelemetry Collector),由 kratos/pkg/trace 模块提供统一的 Span 生命周期管理与上下文透传能力。它默认不依赖 Micrometer(那是 Java 生态),也不用 Sleuth——Go 里没这玩意儿。
Kratos 的 trace 包如何自动注入 Span
Kratos 在 transport 层(http.Server 和 grpc.Server)内置了中间件,会自动从请求头提取 trace-id、span-id 和 parent-id(支持 B3 和 W3C TraceContext 格式),并创建子 Span;响应返回前自动上报。
- HTTP 请求默认从
X-B3-TraceId、X-B3-SpanId等 header 解析上下文 - gRPC 请求从
metadata.MD中读取同名 key - 若无上游传递,则生成新 TraceID,标记为 root span
- 所有 Span 默认携带服务名(
service.name)、主机名、端口等标签
怎么对接 Zipkin 或 OpenTelemetry Collector
关键不是“怎么配”,而是“别手动 new tracer”。Kratos 要求你注册一个全局 trace.Exporter 实例,框架内部会在 Span 结束时调用其 Export 方法。
- 对接 Zipkin:用
zipkin.NewExporter(来自github.com/openzipkin/zipkin-go),Endpoint 设为"http://localhost:9411/api/v2/spans" - 对接 OTLP:用
otlphttp.NewClient+otlptracehttp.NewExporter,Endpoint 通常是"http://otel-collector:4318/v1/traces" - 必须在
app.Init()前完成注册,否则 transport 中间件拿不到 exporter - 注意:Kratos v2.6+ 已弃用旧版
opentracing,推荐直接用go.opentelemetry.io/otel+kratos/pkg/trace/otel
异步任务和数据库调用为什么 Span 断了
不是 Kratos 的 bug,是 Go 协程天然不继承 context。Span 上下文只随 context.Context 传递,一旦脱离 HTTP/gRPC handler 的原始 context,就丢了。
- goroutine 启动时没显式传入带 Span 的 context → 新协程里
trace.SpanFromContext(ctx)返回 nil - MySQL/Redis 客户端未使用 Kratos 封装的 driver(如
kratos/pkg/database/sql)→ 不会自动注入 span 标签 - 消息队列(如 Kafka)消费逻辑没手动调用
trace.StartSpan或trace.WithSpan→ 整个消费链路游离在主链外 - 修复方式:所有异步操作前,用
trace.ContextWithSpan把当前 span 注入新 context,再传给 goroutine
常见配置遗漏和性能坑
生产环境最容易栽在采样率和 reporter 队列上。Kratos 的 trace 包默认全量上报,QPS 高时 Zipkin 直接扛不住。
-
trace.WithSampler(trace.AlwaysSample())是调试用的,上线必须换成trace.ProbabilitySampler(0.01)(1% 采样) - Zipkin Reporter 默认使用内存队列,但没设限长 —— 高并发下可能 OOM,需手动 wrap 一个带 buffer 的 channel
- 服务名(
service.name)必须全局唯一且稳定,不能含 IP 或 PID,否则 Zipkin 里会识别成多个服务 - 日志中打印 TraceID 要用
middleware.GetRequestID(ctx)(Kratos 提供),不是自己从 context 取trace.TraceID字段 —— 后者在非 HTTP 场景可能为空
真正难的从来不是“怎么让第一个 Span 出现在 Zipkin 页面上”,而是保证跨 transport、跨 goroutine、跨 DB 连接的 Span 全部能正确父子关联,且不拖慢主流程。这需要你对 context 传递时机、exporter 异步行为、以及采样策略的实际影响有明确判断,而不是堆配置。











