Kratos链路追踪需同时配置tracing.Server()中间件、全局采样器(如OTEL_TRACES_SAMPLER=always_on)及正确endpoint(如http://127.0.0.1:14268/api/traces),HTTP与gRPC服务须分别注入,客户端需启用tracing.Client()拦截器。

tracing.Server() 必须加在 grpc.Middleware 里,否则 gRPC 请求不会被自动注入 Span
Kratos 的链路追踪基于 OpenTelemetry,但默认不开启采样,所有请求都不会上报 —— 这是本地调试时最常遇到的“没数据”原因。必须显式配置采样器或设置环境变量 OTEL_TRACES_SAMPLER,否则 Jaeger / Zipkin 界面永远空着。
常见错误现象:jaegertracing/all-in-one 容器已启动、端口可访问,但调用接口后 http://127.0.0.1:16686 查不到任何 trace;curl 返回正常,日志里也看不到 tracing 相关 warn/error。
根本原因不是配置路径写错,而是 Kratos 的 tracing.Server() 中间件虽已注册,但底层 OpenTelemetry SDK 默认使用 parentbased_always_off 采样器 —— 即使有父 Span(比如来自网关)也拒绝采样,更别说无上下文的首跳请求。
- 临时解决(开发阶段):启动服务前设环境变量
OTEL_TRACES_SAMPLER=always_on - 生产推荐:在
main.go初始化时调用otel.SetTracerProvider,传入自定义sdktrace.NewTracerProvider并指定sdktrace.WithSampler(sdktrace.AlwaysSample()) - 若需按比例采样(如 1%),改用
sdktrace.TraceIDRatioBased(0.01),避免高并发下压垮 Jaeger collector
注意:tracing.Server() 只负责从 HTTP header 或 gRPC metadata 提取 traceparent 并创建 Span;它不控制采样逻辑,采样由全局 TracerProvider 决定。
配置 endpoint 时不要漏掉 /api/traces 路径
config.yaml 里 trace.endpoint 的值不是 Jaeger collector 的根地址,而是 OpenTelemetry 兼容的接收 endpoint —— 对 jaegertracing/all-in-one 来说,必须是 http://127.0.0.1:14268/api/traces,而不是 http://127.0.0.1:14268 或 http://127.0.0.1:14268/v1/traces。
Jaeger 的 all-in-one 镜像只暴露两个关键端口:14268(接收 OTLP/HTTP traces)、16686(UI 查询)。前者是数据入口,后者是查询出口,二者不可混用。
- 错误写法:
endpoint: http://127.0.0.1:14268→ 请求会 404,Kratos 日志可能静默失败(取决于 log level) - 正确写法:
endpoint: http://127.0.0.1:14268/api/traces - 如果换用 Zipkin,对应 endpoint 是
http://127.0.0.1:9411/api/v2/spans,路径和协议都不同
验证方式:用 curl -X POST http://127.0.0.1:14268/api/traces -H "Content-Type: application/json" -d '[]',返回 202 表示 endpoint 可达。
HTTP 和 gRPC 服务都要单独加 tracing 中间件
Kratos 的 tracing.Server() 不是全局中间件,它只对注册它的 server 生效。gRPC Server 和 HTTP Server 是两个独立实例,必须分别注入:
- gRPC:在
NewGRPCServer的grpc.Middleware(...)列表里加tracing.Server() - HTTP:在
NewHTTPServer的http.Middleware(...)列表里加tracing.Server()
漏掉任意一个,对应协议的请求就不会产生 Span。例如只配了 gRPC tracing,但用 curl 测试 HTTP 接口,Jaeger 就查不到这条链路 —— 它根本没被采集。
另外,tracing.Server() 依赖 otel.GetTextMapPropagator() 解析传播头,所以确保初始化顺序:先 otel.SetTracerProvider,再初始化 server,否则 propagator 可能为 nil 导致提取失败。
跨服务调用时 context 传递不能靠手动拼接
下游服务要能接到上游的 trace 上下文,不能靠 context.WithValue 手动塞 traceID。Kratos 的 client 默认不携带 tracing header,必须显式启用:
- gRPC client:创建时传
grpc.WithUnaryInterceptor(tracing.Client()) - HTTP client:用
http.NewClient并传http.WithMiddleware(tracing.Client())
否则即使上游打了 trace,下游 Span 也会是孤立的 root span,链路断开。常见表现是 Jaeger 里看到多个单节点 Span,时间相近但 traceID 不同。
还有一个易忽略点:Kratos 的 tracing.Client() 默认只对 context.Background() 生效;如果你在 handler 里用 context.WithTimeout 包了一层,要确保把原始 context(含 Span)传进去,而不是新建一个 background context。
真正难调试的不是配置写错,而是采样策略、propagator 初始化时机、client 拦截器缺失这三者组合导致的“部分链路可见、部分断裂”。建议上线前用固定 traceID(如 traceparent: 00-12345678901234567890123456789012-1234567890123456-01)手工注入一次,确认整条路径是否连通。











