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 资源提供程序 |
最佳实践
- 根据您的部署环境选择合适的资源提供程序
- 仅启用必要的提供程序以优化性能
- 确保云平台权限配置正确