在springboot4中使用ADOT的agent注入集成cwagent发送数据和追踪

参考资料

• https://github.com/aws-observability/aws-otel-java-instrumentation
• https://github.com/danvega/ot/blob/master/README.md
• 使用 OpenTelemetry 收集指标和跟踪
• https://github.com/aws-samples/java-on-aws/blob/main/apps/java21/dockerfiles/Dockerfile_03_otel
• https://catalog.workshops.aws/java-on-aws/en-US/observability/build-otel-image#activating-observation-instrumentation

本次使用的示例项目为OpenTelemetry with Spring Boot 4.0 Demo

启动cwagent并开启otel收集功能

cloudwatch agent本质上是一个定制的otel collector，在启动时会将cwagent的配置文件转换为otel collector的配置。我们在本地启动使用以下cloudwatch agent配置开启otel的收集能力

• metrics_collected，开启通过otel收集指标
• traces_collected，开启通过otel收集追踪

{
  "agent": {
    "metrics_collection_interval": 60,
    "run_as_user": "root"
  },
  "metrics": {
    "metrics_collected": {
      "otlp": {
        "grpc_endpoint": "0.0.0.0:4317",
        "http_endpoint": "0.0.0.0:4318"
      }
    },
    "append_dimensions": {
      "InstanceId": "${aws:InstanceId}"
    }
  },
  "traces": {
    "traces_collected": {
      "otlp": {
        "grpc_endpoint": "0.0.0.0:4317",
        "http_endpoint": "0.0.0.0:4318"
      }
    }
  }
}

使用compose挂载配置文件并启动cwagent

services:
  cloudwatch-agent:
    image: 'amazon/cloudwatch-agent:latest'
    ports:
      - '4317:4317'
      - '4318:4318'
    volumes:
      - ./cw-agent-config.json:/etc/cwagentconfig/config.json:ro
    environment:
      - AWS_REGION=cn-north-1

启动日志如下，可见已经成功监听4318端口。应用程序将遥测数据发送到此端点，CloudWatch 代理则将其转发到 X-Ray 和 CloudWatch。

在springboot中开启OpenTelemetry

在springboot中集成OpenTelemetry 的方式有如下三种

• OpenTelemetry Java Agent - Zero code changes but can have version compatibility issues
• Third-party OpenTelemetry Starter - From the OTel project, but pulls in alpha dependencies
• Spring Boot Starter (this demo)— - Official Spring support, stable, well-integrated

为了集成cwagent，我们需要关闭Spring Boot 的 OpenTelemetry 自动配置，转而通过 ADOT 代理的方式注入

spring:
  application:
    name: ot

# 禁用 Spring Boot 的 OpenTelemetry 自动配置，避免与 Java Agent 冲突
management:
  opentelemetry:
    enabled: false
  tracing:
    sampling:
      probability: 1.0

为什么选择 ADOT 代理而不是社区的 OTel 代理？如下是两者的比较

Feature	Community Agent	ADOT Agent
X-Ray trace ID format	✗	✓
AWS resource detection	Basic	Enhanced
Application Signals	✗	✓

下载agent jar文件

wget https://github.com/aws-observability/aws-otel-java-instrumentation/releases/latest/download/aws-opentelemetry-agent.jar

使用如下命令启动应用

export AWS_ADOT_JAVA_INSTRUMENTATION_PATH="aws-opentelemetry-agent.jar"

JAVA_TOOL_OPTIONS="-javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
OTEL_METRICS_EXPORTER="none" \
OTEL_LOGS_EXPORTER="none" \
OTEL_TRACES_EXPORTER="otlp" \
OTEL_TRACES_SAMPLER="always_on" \
OTEL_PROPAGATORS="tracecontext,baggage,xray" \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://localhost:4318/v1/traces" \
OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" \
java -jar /home/ec2-user/ot/target/ot-0.0.1.jar

启动后尝试访问应用，观察trace控制台可以捕获

但是cwagent报错如下

• 警告：某些单位无法转换
• 错误：某些分布指标（distribution metrics）没有条目，如 http.server.requests

检查应用日志发现如下内容。这是由于spring-boot-starter-opentelemetry会引入Micrometer OTLP Registry - Micrometer 的 OTLP 导出器，会自动创建OtlpMeterRegistry并自动导出指标到http://localhost:4318/v1/metrics

2026-01-20T06:11:11.030Z  INFO 32635 --- [ot] [main] [] i.m.c.instrument.push.PushMeterRegistry  : Publishing metrics for OtlpMeterRegistry every 1m to http://localhost:4318/v1/metrics with resource attributes {service.name=ot}

因此，我们在application.yaml中禁用 Micrometer OTLP meter registry，使用 Java Agent 采集所有可观测性数据，避免干扰

  otlp:
    metrics:
      export:
        enabled: false

将OTEL_METRICS_EXPORTER修改为OTLP，即使用 OTLP 协议将指标数据发送到配置的后端端点

export AWS_ADOT_JAVA_INSTRUMENTATION_PATH="/home/ec2-user/ot/aws-opentelemetry-agent.jar"

JAVA_TOOL_OPTIONS="-javaagent:$AWS_ADOT_JAVA_INSTRUMENTATION_PATH" \
OTEL_METRICS_EXPORTER="otlp" \
OTEL_LOGS_EXPORTER="none" \
OTEL_TRACES_EXPORTER="otlp" \
OTEL_TRACES_SAMPLER="always_on" \
OTEL_PROPAGATORS="tracecontext,baggage,xray" \
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://localhost:4318/v1/traces" \
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT="http://localhost:4318/v1/metrics" \
OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf" \
java -jar /home/ec2-user/ot/target/ot-0.0.1.jar

指标也同样能够收集成功

其他同类库的问题

那么什么时候选择OpenTelemetry Starter？

• 实现供应商无关的可观测性（轻松切换后端）
• 跨服务的分布式追踪是优先事项
• 更倾向于基于推送的遥测

什么时候选择Actuator？

• Actuator 用于健康/就绪检查
• OTel 用于遥测