跳到主要内容

Java Agent 配置

Agent 配置来源

Agent 支持多种配置来源,系统会按照以下优先级从高到低的顺序读取和应用配置:

  1. 系统属性(System Properties)
  2. 环境变量
  3. 配置文件
  4. 通过 API 提供的属性:

使用环境变量配置

环境变量是一种灵活且常用的配置方式,特别适合容器化环境和云原生应用。

所有系统属性都可以通过对应的环境变量来设置。

环境变量命名规则

将系统属性转换为环境变量时,请遵循以下规则:

  1. 将所有字母转换为大写
  2. 将所有的 .- 字符替换为 _
示例
  • 系统属性: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 资源提供程序
最佳实践
  • 根据您的部署环境选择合适的资源提供程序
  • 仅启用必要的提供程序以优化性能
  • 确保云平台权限配置正确