Fiber默认不内置链路追踪,需手动实现OpenTelemetry中间件:从HTTP header提取trace context、创建span并注入c.Locals,跨服务调用时须显式inject header以维持链路完整性。

直接上结论:Fiber 本身不内置链路追踪能力,但可以通过 fiber.Handler 中间件 + OpenTelemetry SDK 实现端到端的 span 创建与上下文传播,关键在于正确注入和提取 HTTP header 中的 trace context。
为什么 Fiber 默认不带链路追踪中间件
Fiber 是一个极简、高性能的 Web 框架,设计上刻意避免捆绑可观测性组件。它没有像 Gin 那样提供 otelgin.Middleware 这类开箱即用的封装,所有 tracing 行为必须手动控制 span 生命周期和 context 传递。
- Fiber 的
fiber.Ctx不自动携带 OpenTelemetry 的context.Context,需显式调用otel.GetTextMapPropagator().Extract() - HTTP header 中的 trace context(如
traceparent)不会被自动解析成 span;不手动 extract,跨服务链路必然断裂 - 若只在 handler 内部创建 span 而不关联父 context,该 span 会变成孤立 root span,无法拼接完整链路
如何写一个正确的 Fiber tracing 中间件
核心逻辑是:在请求进入时 extract 上下文并启动 span,在响应返回前结束 span。必须使用 otel.GetTextMapPropagator().Extract() 从 c.Request().Header 中还原 trace context。
- 中间件函数签名必须是
func(*fiber.Ctx) error,且需调用c.Next()保证后续 handler 执行 - span 应通过
tracer.Start()创建,并传入从 header 解析出的 parent context,不能直接用context.Background() - 务必在
defer span.End()前设置 span 属性,例如span.SetAttributes(semconv.HTTPMethodKey.String(c.Method())) - 错误需显式记录:
if c.Response().StatusCode() >= 400 { span.RecordError(fmt.Errorf("http %d", c.Response().StatusCode())) }
示例代码片段:
func TracingMiddleware(tracer trace.Tracer) fiber.Handler {
return func(c *fiber.Ctx) error {
// 从 header 提取父 context
ctx := otel.GetTextMapPropagator().Extract(c.Context(), propagation.HeaderCarrier(c.Request().Header))
// 创建子 span
spanCtx, span := tracer.Start(ctx, "http-server", trace.WithSpanKind(trace.SpanKindServer))
defer span.End()
// 设置常用属性
span.SetAttributes(
semconv.HTTPMethodKey.String(c.Method()),
semconv.HTTPURLKey.String(c.OriginalURL()),
semconv.HTTPRouteKey.String(c.Route().Path),
)
// 继续处理
err := c.Next()
// 记录错误状态
if c.Response().StatusCode() >= 400 {
span.RecordError(fmt.Errorf("http %d", c.Response().StatusCode()))
span.SetStatus(codes.Error, "HTTP error")
}
return err
}
}
跨服务调用时如何保持 trace context
当 Fiber 服务作为客户端调用其他服务(如 HTTP 请求),必须手动将当前 span context 注入 outbound request header,否则下游无法延续链路。
- 不能依赖
http.DefaultClient,需用otelhttp.NewClient()包装或手动 inject - 推荐方式:用
propagation.HeaderCarrier将 context 写入req.Header,再发起请求 - 示例:
otel.GetTextMapPropagator().Inject(spanCtx, propagation.HeaderCarrier(req.Header)) - 注意:
spanCtx必须来自当前活跃 span(即上面中间件中tracer.Start()返回的那个),不是c.Context()
容易被忽略的 Propagator 配置细节
OpenTelemetry 默认使用 W3C TraceContext(traceparent header),但部分旧系统(如 Zipkin)仍依赖 B3 格式。若对接 Jaeger 或自建 collector,需确认 propagator 是否匹配。
- 不显式配置时,
otel.GetTextMapPropagator()返回的是默认的 W3C propagator - 若后端只支持 B3,需初始化时替换:
otel.SetTextMapPropagator(b3.New(b3.WithInjectEncoding(b3.B3MultipleHeader))) - Fiber 中间件里调用
Extract()和Inject()必须使用同一个 propagator 实例,否则解析失败 - 调试时可打印
c.Get("traceparent")确认 header 是否到达,避免因反向代理(如 Nginx)丢 header 导致断链
最常出问题的地方不在 span 创建,而在 context 的 extract/inject 是否发生在同一传播协议下、是否被中间网络组件剥离、以及 span 是否真正继承了 parent —— 这三点漏掉任一,链路就只剩孤岛。











