宣言的設定

宣言的設定は、application.yaml 内で OpenTelemetry の宣言的設定スキーマを使用します。

このアプローチは以下のような場合に便利です。

• 設定するオプションが多い場合
• application.properties や application.yaml では利用できない設定オプションを使いたい場合
• Java エージェントと同じ設定形式を使いたい場合

サポートされるバージョン

宣言的設定は OpenTelemetry Spring Boot スターターのバージョン 2.26.0 以降でサポートされています。

依存関係の管理

はじめにのページに記載されているように、dependencyManagement で opentelemetry-instrumentation-bom をインポートしてください。

はじめに

application.yaml に otel.file_format: "1.0"（または現在の、もしくは希望するバージョン）を追加して、宣言的設定を有効にします。

otel:
  file_format: '1.0'

  resource:
    detection/development:
      detectors:
        - service:
    attributes:
      - name: service.name
        value: my-spring-app

  propagator:
    composite:
      - tracecontext:
      - baggage:

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

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

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

${VAR:default} はコロン1つ（Spring の構文）を使用しており、エージェントのスタンドアロン YAML ファイルで使用される ${VAR:-default} 構文とは異なることに注意してください。

既存の設定を変換する

設定オプションのマッピング

以下のルールは、application.properties / application.yaml の設定オプションが宣言的設定の対応する形式にどのようにマッピングされるかを説明します。

計装の有効化/無効化

宣言的設定では、計装の有効化/無効化は個別のプロパティのかわりに集中管理されたリストを使用します。 計装名には -（kebab-case）ではなく _（snake_case）を使用します。

例:

otel:
  distribution:
    spring_starter:
      instrumentation:
        default_enabled: false
        enabled:
          - jdbc
          - spring_web
        disabled:
          - logback_appender

計装の設定

otel.instrumentation.* 配下の設定オプション（有効化/無効化以外）は、otel.instrumentation/development.java.* にマッピングされます。

1. otel.instrumentation. 接頭辞を取り除く
2. 各セグメントで - を _ に置き換える
3. otel.instrumentation/development.java. 配下に配置する
4. キーの /development 接尾辞は実験的な機能を示す（逆マッピングについては ConfigPropertiesBackedDeclarativeConfigProperties の translateName メソッドを参照）

例:

デフォルトのアルゴリズムに従わない特別なマッピングを持つオプションもあります。

instrumentation/development セクションには2つのトップレベルグループがあります。

• general.* — 言語横断的な設定（HTTP ヘッダー、セマンティック規約の安定性）
• java.* — Java 固有の計装設定

SDK の無効化

SDK の設定

SDK レベルの設定（エクスポーター、プロパゲーター、リソース）は、はじめにの例で示したように、標準の宣言的設定スキーマに従って otel: 直下に配置します。

エージェントの宣言的設定との違い

環境変数によるオーバーライド

Spring の緩和バインディングにより、宣言的設定の YAML の任意の部分を環境変数でオーバーライドできます。

# instrumentation/development 配下のスカラー値をオーバーライド
OTEL_INSTRUMENTATION/DEVELOPMENT_JAVA_FOO_STRING_KEY=new_value

# インデックス付きリスト要素のオーバーライド（例: エクスポーターのエンドポイント）
OTEL_TRACER_PROVIDER_PROCESSORS_0_BATCH_EXPORTER_OTLP_HTTP_ENDPOINT=http://custom:4318/v1/traces

ルール: 大文字にし、. を _ に置き換え、/ はそのまま（例: INSTRUMENTATION/DEVELOPMENT）にし、リストのインデックスには _0_、_1_ を使用します。

これは標準的な Spring の機能であり、application.yaml 内のすべてのキーで動作します。

期間のフォーマット

宣言的設定はミリ秒単位の期間のみをサポートします（例: 5秒の場合は 5000）。 5s のような期間文字列を使用するとエラーになります。

プログラムによる設定

宣言的設定では、AutoConfigurationCustomizerProvider（プログラムによる設定を参照）は DeclarativeConfigurationCustomizerProvider に置き換えられます。 スパンエクスポーターなどのコンポーネントは ComponentProvider API を使用します。 詳細と例については、エージェントの Extension API セクションを参照してください。同じ API が Spring Boot スターターにも適用されます。