iris 框架无开箱即用的 opentelemetry 支持，因官方未提供 irisotel 适配器且 contrib 仓库未收录，需手动注入中间件、显式传递 context 并包装 controller 方法。
Iris 框架在 MVC 架构中集成 OpenTelemetry，必须手动注入中间件并显式包装 Controller 方法——Iris 官方不提供 irisotel 这类专用适配器，也没有自动探针支持，所有 HTTP 入口和业务逻辑的 span 都得靠你手写 context 传递和 tracer 调用。
为什么 Iris 没有开箱即用的 OpenTelemetry 中间件
Iris 是一个轻量、高性能的 Go Web 框架，设计上强调显式控制而非魔法。它不像 Gin 或 Echo 那样有活跃社区维护的 ginotel / echootel 包；go.opentelemetry.io/contrib/instrumentation/github.com/kataras/iris/iris 这个路径根本不存在（截至 2026 年 9 月，官方 contrib 仓库未收录 Iris）。所以你不能依赖自动埋点，也不能把 otelhttp.NewHandler 直接塞进 app.Use()——那会破坏 Iris 的路由参数解析和 MVC controller 绑定逻辑。
HTTP Server 层必须用自定义中间件包装 Router
你得自己写一个中间件，在请求进入时提取 trace 上下文、创建 server span，并确保后续 handler 能拿到带 span 的 context.Context。关键点：
-
otel.GetTextMapPropagator().Extract()必须在中间件开头调用，从ctx.Request.Header解析traceparent - span 必须用
tracer.Start(ctx, "HTTP "+ctx.Method()+" "+ctx.Path())创建，且ctx是 extract 后的新上下文 - 必须在 defer 中调用
span.End()，且要传入otel.WithSpanContext(span.SpanContext())确保子 span 可继承 - 不能直接用
ctx.ResponseWriter写响应码——要 wrap 成responseWriter才能捕获http.status_code和http.response_content_length
示例片段：
func otelMiddleware(tracer trace.Tracer) iris.Handler {
return func(ctx iris.Context) {
prop := otel.GetTextMapPropagator()
carrier := propagation.HeaderCarrier(ctx.Request().Header)
ctxWithSpan := prop.Extract(ctx.Request().Context(), carrier)
spanName := fmt.Sprintf("HTTP %s %s", ctx.Method(), ctx.Path())
ctxWithSpan, span := tracer.Start(ctxWithSpan, spanName,
trace.WithSpanKind(trace.SpanKindServer),
trace.WithAttributes(
semconv.HTTPMethodKey.String(ctx.Method()),
semconv.HTTPURLKey.String(ctx.Request().URL.String()),
semconv.HTTPRouteKey.String(ctx.GetCurrentRoute().FullPath()),
),
)
defer span.End()
// wrap response writer to capture status code
rw := &statusResponseWriter{ResponseWriter: ctx.ResponseWriter(), statusCode: 200}
ctx.SetResponseWriter(rw)
ctx.SetUserValues("otel_ctx", ctxWithSpan) // 供 controller 使用
ctx.Next()
span.SetAttributes(semconv.HTTPStatusCodeKey.Int(rw.statusCode))
}
}
MVC Controller 方法里必须显式获取并传播 context
Iris 的 Controller 是基于反射调用的，不会自动透传 context。你在 Controller 方法签名里不能加 context.Context 参数（Iris 不支持），所以必须从 ctx.UserValue("otel_ctx") 取出已带 span 的 context，并在所有下游调用（DB 查询、HTTP client、goroutine）前手动传入：
- 数据库调用：用
otelsql.InjectDriver("mysql", driver)注册驱动后，db.QueryContext(otelCtx, ...)才会生成 child span - 出向 HTTP 请求：必须用
http.Client{Transport: otelhttp.NewTransport(http.DefaultTransport)}，且调用时用client.Do(req.WithContext(otelCtx)) - 启动 goroutine：不能直接
go doWork()，必须go doWork(otelCtx)，并在函数内用tracer.Start(otelCtx, ...) - 模板渲染、日志打点等非阻塞操作，也建议传
otelCtx以便关联 trace_id
TracerProvider 初始化必须在 main() 开头完成
这是整个链路生效的前提，漏掉就全为 nil span，Jaeger 里空空如也：
- 必须在
main()第一行或紧随init()后执行，不能放在 MVC 初始化之后 -
sdktrace.NewTracerProvider()必须传入resource.WithAttributes(semconv.ServiceNameKey.String("your-iris-app"))，否则 Jaeger 无法按服务名聚合 -
otel.SetTextMapPropagator(propagation.TraceContext{})缺一不可，否则跨服务传播失效 - 别在测试里反复
NewTracerProvider()：单元测试并发运行时会 panic，应复用全局 provider
最简初始化示例：
func main() {
res := resource.NewWithAttributes(
semconv.SchemaURL,
semconv.ServiceNameKey.String("iris-api"),
semconv.ServiceVersionKey.String("1.0.0"),
)
tp := sdktrace.NewTracerProvider(
sdktrace.WithResource(res),
sdktrace.WithSpanProcessor(sdktrace.NewBatchSpanProcessor(exporter)),
)
otel.SetTracerProvider(tp)
otel.SetTextMapPropagator(propagation.TraceContext{})
app := iris.New()
app.Use(otelMiddleware(otel.Tracer("iris")))
// register MVC
mvc.New(app.Party("/api")).Register(...).Handle(new(MyController))
app.Listen(":8080")
}
真正容易被忽略的是：Iris 的 Controller 方法本身不参与 span 生命周期管理，你得在每个方法内部手动 start/end 子 span，同时确保所有异步分支都拿到同一份 otelCtx——不是靠框架，而是靠你每一处调用时的显式传递。
