如何通过Java Agent实现Quarkus应用无依赖修改的自动埋点

方案核心说明 #

无需修改项目代码、无需新增任何项目依赖，通过官方OpenTelemetry Java Agent即可实现Quarkus应用的全链路自动埋点，完全替代手动引入依赖、修改配置文件的埋点方式。

操作步骤 #

• 前置清理：移除项目中已引入的io.quarkus:quarkus-opentelemetry-exporter-otlp及所有Quarkus OpenTelemetry相关依赖，删除application.properties中所有quarkus.opentelemetry.*开头的配置项，避免和Agent注入的埋点逻辑冲突。
• 下载对应稳定版本的OpenTelemetry Java Agent包到应用部署目录。
• 启动Quarkus应用时挂载Agent，所有链路配置通过JVM启动参数传入，不需要修改项目内任何文件，启动命令示例：

java -javaagent:/your/local/path/opentelemetry-javaagent.jar \
  # 关闭Quarkus自带的OTel集成，避免冲突
  -Dquarkus.opentelemetry.enabled=false \
  # 配置服务名
  -Dotel.service.name=your-quarkus-service \
  # 配置OTLP链路上报端点
  -Dotel.exporter.otlp.traces.endpoint=http://localhost:4317 \
  # 配置上报鉴权头
  -Dotel.exporter.otlp.traces.headers=Authorization=Bearer my_secret \
  -jar your-quarkus-app-runner.jar

注意事项 #

• 该方案仅支持Quarkus的JVM运行模式。Quarkus native镜像为AOT提前编译产物，不支持运行时动态挂载Java Agent，无法通过该方式实现无侵入埋点。
• 版本匹配要求：Quarkus 2.x系列建议搭配1.25.x~1.27.x版本的OpenTelemetry Java Agent；Quarkus 3.x系列基于Jakarta EE规范，需要搭配1.28.0及以上版本的Agent，否则会出现组件埋点失效、链路断档问题。
• 默认配置下Agent会自动覆盖Quarkus常用组件的埋点，包括REST接口、Reactive路由、JDBC/Redis/MQ客户端、HTTP调用客户端等，不需要额外开启配置。

内容的提问来源于stack exchange，提问作者Shivam Jaiswal