Java Agent 声明式配置

声明式配置使用 YAML 文件代替环境变量或系统属性。

此方法在以下情况下很有用

您有许多配置选项需要设置
您想使用环境变量或系统属性中没有提供的配置选项

与环境变量一样，配置语法与语言无关，适用于所有支持声明式配置的 OpenTelemetry Java SDK，包括 OpenTelemetry Java agent。

警告

声明式配置是实验性的。

支持的版本

声明式配置支持 **OpenTelemetry Java agent 版本 2.20.0 及更高版本**。

入门

将下面的配置文件另存为 otel-config.yaml。
将以下内容添加到您的 JVM 启动参数中
-Dotel.experimental.config.file=/path/to/otel-config.yaml

file_format: '1.0-rc.1'

resource:
  attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}
  detection/development:
    detectors:
      - service: # will add "service.instance.id" and "service.name" from OTEL_SERVICE_NAME

propagator:
  composite:
    - tracecontext:
    - baggage:

tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT:-https://:4318/v1/traces}

meter_provider:
  readers:
    - periodic:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_METRICS_ENDPOINT:-https://:4318/v1/metrics}

logger_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_LOGS_ENDPOINT:-https://:4318/v1/logs}

有关声明式配置的更通用的入门指南，请参考 SDK 声明式配置文档。

本页重点介绍 OpenTelemetry Java agent 的具体细节。

配置选项映射

当您想将现有的环境变量或系统属性配置映射到声明式配置时，请使用以下规则

如果配置选项以 otel.javaagent. 开头（例如 otel.javaagent.logging），那么它很可能是只能通过环境变量或系统属性设置的属性（有关详细信息，请参阅下面的仅限环境变量和系统属性的选项部分）。否则，请删除 otel.javaagent. 前缀并将其放在下面的 agent 部分。
如果配置选项以 otel.instrumentation. 开头（例如 otel.instrumentation.spring-batch.experimental.chunk.new-trace），则删除 otel.instrumentation. 前缀并将其放在下面的 instrumentation 部分。
否则，该选项很可能属于 SDK 配置。在迁移配置中找到正确的节。如果您有一个像 otel.bsp.schedule.delay 这样的系统属性，请在迁移配置中查找对应的环境变量 OTEL_BSP_SCHEDULE_DELAY。
使用 . 来创建缩进级别。
将 - 转换为 _。
在适当的地方使用 YAML 布尔值和整数类型（例如，true 而不是 "true"，5000 而不是 "5000"）。
具有特殊映射的选项将在下面单独说明。

instrumentation/development:
  general:
    peer:
      service_mapping: # was "otel.instrumentation.common.peer-service-mapping"
        - peer: 1.2.3.4
          service: FooService
        - peer: 2.3.4.5
          service: BarService
    http:
      client:
        request_captured_headers: # was otel.instrumentation.http.client.capture-request-headers
          - Content-Type
          - Accept
        response_captured_headers: # was otel.instrumentation.http.client.capture-response-headers
          - Content-Type
          - Content-Encoding
      server:
        request_captured_headers: # was otel.instrumentation.http.server.capture-request-headers
          - Content-Type
          - Accept
        response_captured_headers: # was otel.instrumentation.http.server.capture-response-headers
          - Content-Type
          - Content-Encoding
  java:
    agent:
      # was otel.instrumentation.common.default-enabled
      # instrumentation_mode: none  # was false
      instrumentation_mode: default # was true
    spring_batch:
      experimental:
        chunk:
          new_trace: true

仅限环境变量和系统属性的选项

以下配置选项受声明式配置支持，但只能通过环境变量或系统属性访问

otel.javaagent.configuration-file（但使用声明式配置时应不需要）
otel.javaagent.debug
otel.javaagent.enabled
otel.javaagent.experimental.field-injection.enabled
otel.javaagent.experimental.security-manager-support.enabled
otel.javaagent.extensions
otel.javaagent.logging.application.logs-buffer-max-records
otel.javaagent.logging

这些选项在 agent 启动时需要，在读取声明式配置文件之前。

持续时间格式

声明式配置 **仅支持毫秒为单位的持续时间**（例如，5000 表示 5 秒）。
如果您使用 OTEL_BSP_SCHEDULE_DELAY=5s（对环境变量有效，但对声明式配置无效），您将收到一个错误。

示例

tracer_provider:
  processors:
    - batch:
        schedule_delay: ${OTEL_BSP_SCHEDULE_DELAY:-5000}

行为差异

资源属性 telemetry.distro.name（由 Java agent 默认添加）的值为 opentelemetry-javaagent 而不是 opentelemetry-java-instrumentation（将在 3.0 版本中重新统一）。

尚不支持的功能

仍需要环境变量或系统属性的功能

某些受环境变量和系统属性支持的功能尚未受到声明式配置的支持

以下设置仍需要通过环境变量或系统属性进行设置

otel.experimental.javascript-snippet
otel.instrumentation.aws-sdk.experimental-record-individual-http-error
otel.instrumentation.aws-sdk.experimental-span-attributes
otel.instrumentation.aws-sdk.experimental-use-propagator-for-messaging
otel.instrumentation.common.db-statement-sanitizer.enabled
otel.instrumentation.common.logging.span-id
otel.instrumentation.common.logging.trace-flags
otel.instrumentation.common.logging.trace-id
otel.instrumentation.experimental.span-suppression-strategy
otel.instrumentation.genai.capture-message-content
otel.instrumentation.jdbc.experimental.capture-query-parameters
otel.instrumentation.jdbc.experimental.transaction.enabled
otel.instrumentation.log4j-context-data.add-baggage
otel.instrumentation.messaging.experimental.capture-headers
otel.instrumentation.messaging.experimental.receive-telemetry.enabled
otel.javaagent.experimental.thread-propagation-debugger.enabled
otel.semconv-stability.opt-in

完全不支持的功能

Java agent 的声明式配置尚不支持的功能

otel.instrumentation.common.mdc.resource-attributes
otel.javaagent.add-thread-details

Contrib 的声明式配置尚不支持的功能

Spring Boot starter 的限制

最后，Spring Boot starter 尚不支持声明式配置

但是，您已经可以使用 application.yaml 来配置 OpenTelemetry Spring Boot starter。

扩展 API

扩展使用新的声明式配置 API。

使用 AutoConfigurationCustomizerProvider 的扩展需要迁移到新的 DeclarativeConfigurationCustomizerProvider API。查看旧的 AgentTracerProviderConfigurer 如何映射到新的 SpanLoggingCustomizerProvider。
像 span exporters 这样的组件现在需要使用 ComponentProvider API。查看同时支持旧 API 和新 API 的 Baggage Processor 作为示例。

Feedback

这个页面有用吗？

谢谢。您的反馈受到赞赏！

请让我们知道我们如何改进此页面。您的反馈受到赞赏！

最后修改于 2025 年 12 月 22 日：添加 Java Agent 说明链接 (#8690) (dabd3022)