Akka HTTP应用中OpenTelemetry无法追踪HTTP请求及链路聚合问题

1. 确认OTEL Agent与Akka HTTP的版本兼容性 #

OTEL Java Agent对Akka HTTP的自动追踪并非全版本兼容，比如v1.20+版本的Agent对Akka HTTP 10.2.x及以上版本支持更稳定。如果你的Agent版本过旧或Akka HTTP版本太新，自动instrumentation会直接失效，自然抓不到HTTP请求的追踪数据。

2. 强制启用Akka HTTP的Instrumentation #

很多场景下OTEL Agent默认未开启Akka HTTP的追踪插件，直接在SBT的javaOptions中添加以下配置：

run / javaOptions ++= Seq(
  // 保留原有配置...
  "-Dotel.instrumentation.akka-http.enabled=true",
  "-Dotel.instrumentation.akka-http.server.enabled=true"
)

不要依赖默认配置，显式开启才能确保Agent加载Akka HTTP的追踪逻辑。

3. 修复链路拆分：解决异步上下文传播问题 #

同业务流程拆分为多个独立Trace，本质是OTEL上下文在异步操作中丢失——比如Akka Future、Actor消息传递时，SpanContext没有被正确传递。

针对Future的修复： #

创建Future时手动绑定当前OTEL上下文：

import io.opentelemetry.context.Context
import scala.concurrent.ExecutionContext

// 获取当前线程的OTEL上下文
val currentCtx = Context.current()
Future {
  // 将上下文绑定到当前执行线程
  val scope = currentCtx.makeCurrent()
  try {
    // 业务逻辑代码
  } finally {
    scope.close()
  }
}(ExecutionContext.global)

针对Akka Actor的修复： #

启用OTEL的Actor instrumentation，在javaOptions中添加：

"-Dotel.instrumentation.akka-actor.enabled=true"

Agent会自动在Actor消息传递时传播上下文，避免链路断裂。

4. 补全OTLP Exporter的明确配置 #

虽然Jaeger已开启OTLP端口，但默认端点可能存在识别问题，显式指定配置：

run / javaOptions ++= Seq(
  // 保留原有配置...
  "-Dotel.exporter.otlp.endpoint=http://localhost:4317",
  "-Dotel.exporter.otlp.protocol=grpc"
)

可开启调试日志排查问题：

"-Dotel.javaagent.debug=true",
"-Dlogging.level.io.opentelemetry=debug"

日志中能查看Agent加载状态、追踪数据发送情况及错误信息。

5. 手动添加路由追踪（自动Instrumentation失效时的兜底方案） #

如果以上配置仍未生效，直接为Akka HTTP路由手动添加追踪逻辑：

import akka.http.scaladsl.server.Directives._
import io.opentelemetry.api.trace.{Tracer, SpanKind}
import io.opentelemetry.context.Scope

// 获取全局Tracer实例
val tracer = io.opentelemetry.api.GlobalOpenTelemetry.getTracer("akka-http-manual-tracer")

// 封装路由追踪的自定义Directive
def traceRoute: Directive0 = extractRequest { req =>
  val span = tracer.spanBuilder(s"${req.method.name} ${req.uri.path}")
    .setSpanKind(SpanKind.SERVER)
    .startSpan()
  mapRequestContext { ctx =>
    val scope = span.makeCurrent()
    ctx.withHttpResponseMapped(_.map(_ => {
      span.end()
      scope.close()
    }))
  }
}

// 使用该Directive包裹业务路由
val myApiRoute = traceRoute {
  path("api" / "pantry" / "items") {
    get {
      // 业务逻辑代码
      complete(200 -> "Success")
    }
  }
}

6. 基础配置检查 #

• 确保fork := true生效：Java Agent必须在fork的进程中才能加载，SBT默认可能不启用fork模式。
• 确认Akka HTTP依赖完整：比如是否包含akka-http-core模块，Agent需要识别这些核心类才能实现自动追踪。

内容的提问来源于stack exchange，提问作者Julián Carvajal Montoya