OpenTelemetry Java Agent 在 Docker 环境中配置 OTLP 导出失败的解决方案

问题背景

在使用 OpenTelemetry Java Agent 进行应用监控时，开发者经常会遇到在 Docker 容器环境中 OTLP 导出失败的问题。典型表现为应用在宿主机本地运行时可正常导出日志和指标数据，但在容器化部署后出现连接失败错误，错误信息显示无法连接到 localhost:4318。

核心问题分析

这个问题本质上源于 OpenTelemetry Java Agent 的配置机制特殊性。与常规的 Spring Boot 应用配置不同，Java Agent 无法直接读取应用配置文件（如 application.yml）中的 OpenTelemetry 相关配置。当开发者将这些配置错误地放置在 Spring 配置文件中时，在容器环境中就会出现连接失败的情况。

解决方案详解

正确的配置方式

在 Docker 容器环境中，必须通过环境变量来配置 OpenTelemetry Java Agent。这是 Java Agent 的标准配置方式，与常规的应用配置有所区别。以下是关键的环境变量配置示例：

ENV OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://otel-collector:4318/v1/logs
ENV OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://otel-collector:4318
ENV OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://otel-collector:4318/v1/traces

配置要点说明

1. 服务发现机制：在 Docker Compose 环境中，可以使用服务名称（如 otel-collector）作为主机名，Docker 内置的 DNS 解析会自动处理服务发现。

2. 端口一致性：确保配置的端口号（如 4318）与 Collector 服务实际暴露的端口一致。

3. 协议路径：注意不同信号类型（logs/metrics/traces）可能需要不同的 URL 路径。

4. 环境变量格式：OpenTelemetry 环境变量必须使用全大写和下划线的格式。

深入理解配置机制

OpenTelemetry Java Agent 采用了一种独特的配置加载机制。它在 JVM 启动时通过-javaagent 参数加载，此时 Spring 环境尚未初始化，因此无法读取 Spring 的配置。Agent 会优先检查以下配置源：

1. 系统属性（-D 参数）
2. 环境变量
3. 配置文件（需要特殊指定路径）

在容器化环境中，环境变量是最可靠和方便的配置方式，因为：

• 可以通过 Dockerfile 或 docker-compose.yml 统一管理
• 不受应用框架限制
• 便于在不同环境间保持一致

最佳实践建议

1. 统一配置管理：建议将所有 OpenTelemetry 相关配置集中通过环境变量设置，保持一致性。

2. 网络连通性验证：在容器启动后，可以通过 exec 进入容器，使用 curl 等工具测试到 Collector 的网络连通性。

3. 日志级别调整：在调试阶段可以设置 OTEL_LOG_LEVEL=debug 获取更详细的日志信息。

4. 版本兼容性：确保 Java Agent 版本与 Collector 版本兼容，避免因协议不匹配导致的问题。

总结

OpenTelemetry Java Agent 在容器化环境中的配置需要特别注意其特殊的配置加载机制。通过正确使用环境变量进行配置，可以确保监控数据能够正常导出到 Collector。理解这一机制差异，是成功实现分布式追踪和指标监控的关键一步。对于从传统配置方式转向 OpenTelemetry 的开发者来说，这一认知转变尤为重要。