observability-edot-java-instrument

用途

本技能用于为 Java 应用程序接入 Elastic Distribution of OpenTelemetry（EDOT）Java agent，从而实现自动的追踪、指标与日志采集。当需要为 Java 应用添加可观测性能力时使用。

使用前准备

在做出任何更改前，应先阅读相关设置指南，包括 EDOT Java 设置、OpenTelemetry Java agent 以及 EDOT Java 配置文档。

主要能力

通过挂载 Java agent，自动完成 tracing、metrics 与 logs 的采集，并导出到指定的 OTLP 端点。

使用方式

1. 使用 elastic-otel-javaagent.jar，需从 Maven Central 下载，而不是作为 Maven/Gradle 的编译依赖引入。
2. 通过 -javaagent:/path/to/elastic-otel-javaagent.jar 或 JAVA_TOOL_OPTIONS="-javaagent:/path/to/elastic-otel-javaagent.jar" 挂载。若未挂载，agent 不会生效。
3. 需要设置恰好三个必需的环境变量：
   • OTEL_SERVICE_NAME
   • OTEL_EXPORTER_OTLP_ENDPOINT——必须是受管理的 OTLP 端点或 EDOT Collector 的 URL。切勿使用 APM Server URL（不要使用 apm-server，不要使用 :8200，不要使用 /intake/v2/events）。
   • OTEL_EXPORTER_OTLP_HEADERS——值为 "Authorization=ApiKey <key>" 或 "Authorization=Bearer <token>"。
4. 不要设置 OTEL_TRACES_EXPORTER、OTEL_METRICS_EXPORTER 或 OTEL_LOGS_EXPORTER——默认值已经正确。

限制与注意事项

• 切勿在同一个 JVM 上同时运行经典 Elastic APM agent 和 EDOT agent。
• 未通过 javaagent 挂载时，该 agent 不会产生任何效果。
• 端点必须使用受管理的 OTLP 端点或 EDOT Collector URL，不能使用 APM Server URL。

示例

完整的 Dockerfile 和 docker-compose 示例请参见 EDOT Java 设置指南。