Kratos 集成 OpenTelemetry 默认自动采集 Trace(启用 tracing.Server()/Client() 中间件即可),但 Metrics 和 Logs 需手动初始化 MeterProvider 和 otelslog.Logger 并正确传入 context。

Kratos 框架集成 OpenTelemetry 不需要手动写埋点代码,只要启用内置 tracing 中间件 + 正确配置导出器,就能自动采集 HTTP/gRPC 请求链路、Span 生命周期、标准语义属性(如 http.method、http.status_code、net.peer.name);但指标(Metrics)和日志(Logs)默认不自动采集,必须显式注册对应的 SDK 组件。
kratos 的 tracing 中间件怎么启用?
Kratos v2.6+ 内置了基于 OpenTelemetry 的 tracing 中间件,它会自动为 HTTP 和 gRPC 服务端/客户端注入 Span,并透传 W3C traceparent。关键不是“加依赖”,而是“正确加载中间件”:
- 确保已引入
go.opentelemetry.io/otel及其导出器(如go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc) - 在服务启动时,用
otel.Tracer初始化全局 tracer,并通过otel.SetTextMapPropagator设置 W3C 传播器 - HTTP Server 启动时传入
tracing.Server()中间件;gRPC Client 创建时传入tracing.Client() - 不要重复调用
otel.Tracer("xxx")创建多个 tracer 实例——Kratos 的中间件只认全局默认 tracer
示例片段:
import (
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
"go.opentelemetry.io/otel/propagation"
"go.opentelemetry.io/otel/sdk/resource"
sdktrace "go.opentelemetry.io/otel/sdk/trace"
semconv "go.opentelemetry.io/otel/semconv/v1.21.0"
)
func initTracer() {
exp, _ := otlptracegrpc.New(context.Background())
tp := sdktrace.NewTracerProvider(
sdktrace.WithBatcher(exp),
sdktrace.WithResource(resource.NewWithAttributes(
semconv.SchemaURL,
semconv.ServiceNameKey.String("user-service"),
)),
)
otel.SetTracerProvider(tp)
otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(propagation.TraceContext{}, propagation.Baggage{}))
}
// 启动 HTTP Server 时
httpSrv := http.NewServer(
http.Address(":8000"),
http.Middleware(
tracing.Server(), // ← 这才是关键
),
)
为什么 Metrics 没有自动上报?
Kratos 的 tracing 中间件只负责 Trace 数据,不处理 Metrics。OpenTelemetry Go SDK 的 Metrics 是独立模块,且目前(v1.24+)仍处于正式版过渡期,API 不稳定,Kratos 未做任何封装或默认集成。
- 必须手动初始化
metric.MeterProvider,并注册到otel.SetMeterProvider - 需自行调用
meter.Int64Counter、meter.Float64Histogram等创建指标,Kratos 不提供像 Spring Boot 那样的自动 HTTP 指标(如http_server_requests_seconds) - 常见漏点:忘记调用
mp.ForceFlush(context.Background())或未配置 exporter(如 OTLP、Prometheus pull endpoint) - 推荐组合:用
prometheus.Exporter暴露/metrics端点,再由 Prometheus 抓取;避免直接走 OTLP 推送 Metrics(Go SDK 对 OTLP metrics 支持尚不成熟)
如何让日志(Log)带上 TraceID?
Kratos 默认日志(log.Logger)不感知上下文,也不会自动注入 trace_id 或 span_id。要实现日志-链路关联,必须桥接 OpenTelemetry Context 与日志字段:
- 使用
go.opentelemetry.io/contrib/bridges/otelslog包,它提供otelslog.NewLogger,能自动从context.Context提取 trace/span ID 并写入日志字段 - 替换 Kratos 默认 logger:在
app.Run()前调用log.SetLogger(otelslog.NewLogger("my-service")) - 确保业务代码中所有日志调用都携带 context(如
log.InfoContext(ctx, "user created")),否则无法提取 trace 上下文 - 注意:
otelslog目前不支持结构化日志字段透传(如 zap 的String()),仅注入固定字段trace_id、span_id
采样率和性能影响怎么控制?
Kratos 的 tracing 中间件默认使用 AlwaysSample,全量采集 Span —— 这在压测或上线初期便于排查,但生产环境高 QPS 下会导致显著内存与网络开销(尤其 Span 数量与请求量呈线性关系)。
- 改用
ParentBased(TraceIDRatioBased(0.01))实现 1% 采样,可大幅降低资源消耗 - 采样策略必须在 tracer provider 初始化时设置,不能在中间件里动态改:传入
sdktrace.WithSampler(sampler) - 若需 tail-based 动态采样(如只保留错误 Span 或慢 Span),需换用 Jaeger 或 Tempo 后端 + 自定义 collector,Kratos 层无法支持
- 实测数据:QPS 5k 场景下,1% 采样比全量减少约 87% 的 OTLP 请求体积和 60% 的 GC 压力
真正容易被忽略的,是 Metrics 和 Logs 的“非自动性”——它们不像 Trace 那样有中间件兜底,必须一行行写、一个个配、一次次验证导出是否生效。一个没 flush 的 meter,或一个没传 ctx 的 log,就会导致可观测性三支柱缺腿。


















