Java Agent 配置
Agent 配置来源
Agent 支持多种配置来源，系统会按照以下优先级从高到低的顺序读取和应用配置：
使用环境变量配置
环境变量是一种灵活且常用的配置方式，特别适合容器化环境和云原生应用。
所有系统属性都可以通过对应的环境变量来设置。
环境变量命名规则
将系统属性转换为环境变量时，请遵循以下规则：
- 将所有字母转换为大写
- 将所有的
.和-字符替换为_
示例
- 系统属性：
otel.instrumentation.common.default-enabled - 对应的环境变量：
OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED
配置文件
配置名称： otel.javaagent.configuration-file
指定包含 Agent 配置的 Java 属性文件路径。
适合需要集中管理配置的环境，便于配置的版本控制和管理。
扩展功能配置
配置名称： otel.javaagent.extensions
用于配置 Agent 扩展：
- 可以指向单个 jar 文件或包含多个 jar 文件的目录
- 目录中的每个 jar 文件都会被视为独立的扩展
- 了解更多扩展开发信息
日志配置
配置名称： otel.javaagent.logging
支持以下日志模式：
| 模式 | 说明 | 适用场景 |
|---|---|---|
simple | • 使用标准错误流输出 • 仅输出 INFO 及以上级别日志 • 默认模式 | 开发环境和简单部署场景 |
none | • 完全禁用日志输出 • 包括 Agent 版本信息 | 对日志敏感的生产环境 |
application | • 重定向到应用的 slf4j 日志系统 • 支持通过应用日志配置文件控制 • 适合单 jar 应用和 Spring Boot | 需要统一日志管理的场景 |
提示
使用 application 模式时，请在生产环境部署前进行充分测试，确保日志配置正确生效。
SDK 配置
Agent 的基础功能通过 SDK 自动配置模块提供。详细配置参数请参考配置文档。
注意
Java Agent 2.0+ 版本默认使用 http/protobuf 协议（不同于 SDK 的默认 grpc 协议）：
- 适用于 Java Agent 2.0+ 版本
- 适用于 OpenTelemetry Spring Boot Starter
- 无需额外配置即可使用
资源提供程序配置
除了标准的 SDK 资源配置，您还可以启用以下额外的资源提供程序：
| 提供程序 | 配置名称 | 默认值 | 说明 |
|---|---|---|---|
| AWS | 系统属性otel.resource.providers.aws.enabled环境变量 OTEL_RESOURCE_PROVIDERS_AWS_ENABLED | false | 启用 AWS 资源提供程序 |
| GCP | 系统属性otel.resource.providers.gcp.enabled环境变量 OTEL_RESOURCE_PROVIDERS_GCP_ENABLED | false | 启用 GCP 资源提供程序 |
最佳实践
- 根据您的部署环境选择合适的资源提供程序
- 仅启用必要的提供程序以优化性能
- 确保云平台权限配置正确