宣言的設定のジャーニー: トレースにおけるヘルスチェックエンドポイントを無視するのに5年かかった理由
過去数年間にわたり、Java OpenTelemetryに対する最も持続的に人気のある機能リクエストのひとつは、効率的にヘルスチェックエンドポイントのスパンをドロップする（またはその他の価値が低くコストのかかるエンドポイントをドロップする）機能でした。 このイシューは2020年8月に最初に提起されましたが、驚くほど長い間、包括的なソリューションは見つかりませんでした。 なぜこの一見単純な問題を解決するのに5年もかかったのでしょうか？ その答えは、OpenTelemetryの設定システムの基本原則と、より堅牢で柔軟なアプローチである宣言的設定へのジャーニーにあります。
OpenTelemetryは、当初から設定のために環境変数に依存していました。 これは環境変数が言語を問わず普遍的に利用可能であり、解析が容易であるという理由からの選択でした。 しかし、より複雑な設定のユースケースの必要性が高まるにつれて、単純な文字列ベースの環境変数の制限がますます明らかになり、高度な設定の管理が煩雑かつ困難になりました。
宣言的設定を導入は、YAMLファイルを活用してOpenTelemetryの設定を定義する強力な進化です。 この変化により、任意のツリー構造のソースからデータを読み取ることが可能になり、複雑な設定へのアプローチが根本的に変わります。 このポストを通じて、宣言的設定が過去の課題に対してどのようにエレガントなソリューションを提供するかを探り、Javaにおけるヘルスチェック除外などの実用的なユースケースでその即時的な影響を示します。
はじめに
設定ファイルは言語に依存しないため、一度ファイルを作成すれば、すべてのSDKで使用できます。
唯一の例外は、特定の言語名を持ち、その言語にのみ関連するパラメータです（たとえばinstrumentation/development.java.spring_batchパラメータ）。
宣言的設定は 実験的 であるため、まだ変更される可能性があることに注意してください。
次の例は、開始するために使用できる基本的な設定ファイルです。
file_format: '1.0-rc.1'
resource:
attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}
detection/development:
detectors:
- service: # OTEL_SERVICE_NAMEから"service.instance.id"と"service.name"を追加します
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}
実験的な宣言的設定オプションを有効にするには、アプリケーションにOTEL_EXPERIMENTAL_CONFIG_FILE=/path/to/otel-config.yamlを渡すだけです。
この変数は、執筆時点ではJavaエージェントとJavaScriptでのみ機能します。
Javaにおける宣言的設定
それでは、Javaエコシステム内での宣言的設定のより幅広い実装を見てみましょう。 この分野の先駆的な言語としてJavaエージェント2.21+は現在、宣言的設定を完全にサポートしており、ほとんどの計装と機能がすでに動作しています。 残りの機能を2026年中に組み込むよう取り組んでおり、プロジェクトボードで進捗を追跡し、まだサポートされていない機能のリストを参照できます。
新規に始めるか、環境変数を使用して移行するかに応じて、活用できるリソースがいくつかあります。
- 前のセクションの基本的な（言語に依存しない）設定ファイルの例は、それ以上のカスタマイズが不要な場合に最も迅速に開始する方法です。
- 移行設定ファイルは、古い環境変数をYAMLスキーマにマッピングし、環境変数がすでに設定されているワークロードのドロップイン置換を可能にします。
- The full configuration file (“kitchen sink”) shows the entire schema, annotated with documentation as comments.
- 完全な設定ファイル（「キッチンシンク」）は、ドキュメントがコメントとして注釈された完全なスキーマを示しています。 これは、利用可能なすべてのオプションとそのデフォルトを確認したいユーザーに役立ちます。
上記のファイルはすべて、宣言的設定をサポートする任意の言語で機能します。
さらに、設定ファイルの計装セクションににはJavaエージェントに特有の多くの設定があります。
たとえば、アプリケーションにシステムプロパティotel.instrumentation.spring-batch.experimental.chunk.new-traceがある場合、otel.instrumentation接頭辞を削除し、.で分割し、-を_に変換することで、宣言的ファイルを作成できます。
file_format: '1.0-rc.1'
# ...
instrumentation/development:
java:
spring_batch:
experimental:
chunk:
new_trace: true
この設定により、開発者は通常どおりJava計装を使用し続け、選択したオブザーバビリティバックエンドにテレメトリーデータを送信できます。 さらに、宣言的ファイルは必要に応じてパラメータを拡張および追加する柔軟性を提供し、オブザーバビリティ設定を高度にカスタマイズおよび細かく制御できます。
ヘルスチェックの除外
冒頭で述べたように、Javaコミュニティで最も人気のある機能リクエストのひとつは、ヘルスチェック（またはその他の重要でない、またはノイズの多いリソース）をトレースの生成から除外できるようにすることでした。
これを実現するには、以下に示すようにtracer_provider設定内に新しいsamplerブロックを追加する必要があります。
file_format: '1.0-rc.1'
# ... 残りの構成 ...
tracer_provider:
# ヘルスチェックエンドポイントを除外するためのサンプリングを構成します。
sampler:
rule_based_routing:
fallback_sampler:
always_on:
span_kind: SERVER
rules:
# ルールが一致した場合に実行するアクション。DROPまたはRECORD_AND_SAMPLEである必要があります。
- action: DROP
# 一致させるスパン属性。
attribute: url.path
# span属性と比較するパターン。
pattern: /actuator.*
# ... 残りのtrace_provider設定 ...
使用可能なオプションの詳細については、Javaサンプラーのドキュメントを参照してください。
ぜひご自身で試してみてください。
- 完全な設定を保存
- Javaエージェントを
-Dotel.experimental.config.file=/path/to/otel-config.yamlで実行
可用性
宣言的設定について読んだ後、どこで利用できるのか、そしてどのように使い始めることができるのか疑問に思うかもしれません。 開始方法とサポートされている言語についてのガイダンスは、ドキュメントで見つけることができます。 このポスト執筆時点では、Javaは完全に準拠しており、PHP、JavaScript、Goは部分的に準拠しています。 最新のステータスを確認するには、コンプライアンスマトリックスまたは 言語実装の追跡イシューを確認してください。
Java
前述の通り、Javaの宣言的設定は実験的ですが、すぐに使用できます。
先ほど説明した例を使用して、新しい設定をセットアップしてください。
ご質問やフィードバックがある場合は、CNCF Slackの#otel-javaでお問い合わせください。
他の言語メンテナーへの注意: 宣言的設定と環境変数を共通インターフェースに適応させるブリッジモジュールを作成することが有用です。 Javaの場合、これは宣言的設定ブリッジです。
JavaScript
JavaScriptのSDK実装は、現在開発中です。
opentelemetry-configurationという新しいパッケージが作成されており、環境変数と宣言的設定の両方を処理します。
このアプローチにより、新しいパッケージが両方を処理し、両方のケースで同じ設定モデルを返すため、ユーザーは環境変数と設定ファイルの間で切り替えるときに計装を変更する必要がありません。
現在、この設定パッケージは他の計装パッケージに追加されており、宣言的設定を活用できます。
ご質問がある場合は、CNCF Slackの#otel-jsでお問い合わせください。
PHP
PHP実装は部分的に準拠しており、設定ファイルから初期化することで使用を開始できます。
ヘルプやフィードバックについては、CNCF Slackの#otel-phpでお問い合わせください。
Go
Goには、宣言的設定の部分的な実装があります。
サポートされている各スキーマバージョンごとに対応するパッケージディレクトリが存在します。
たとえば、go.opentelemetry.io/contrib/otelconf/v0.3.0をインポートすると、設定スキーマのバージョン0.3.0をサポートするコードが得られます。
利用可能なすべてのバージョンは、パッケージインデックスで確認できます。
使用方法について質問がある場合は、CNCF Slackの#otel-goでお問い合わせください。
ジャーニー
では、なぜ実際にトレースでヘルスチェックエンドポイントを無視するのに5年もかかったのでしょうか？
宣言的設定へのジャーニー、そしてそれに続くヘルスチェック除外のソリューションは、厳格な仕様を通じて持続可能なソリューションを構築するというOpenTelemetryの中心的な原則を強調しています。
OpenTelemetryは当初から環境変数に依存していましたが、普遍的に利用可能である一方で、高度な設定にはますます複雑になることが判明しました。 新しい環境変数は最終的に許可されなくなり、より堅牢なソリューションで埋める必要のある空白が生まれました。
このブログ投稿で紹介したように、その代替は宣言的設定です。
正確な構文とセマンティクスを作成し、合意に達することは時間がかかり、時には疲れ果ててしまうプロセスでした。
たとえば、環境変数を埋め込む方法についていくつかの提案を議論し、現在の
${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}を使用するソリューションにたどり着きました。
このプロセスは、OpenTelemetryコミュニティがどのように機能するかの強力なケーススタディとして役立ちます。 これは、コンセンサスを確立し、コラボレーションの促進し、多様なプロジェクトを横断して重要な新機能を導入して実装を推進するために必要な集団的努力の証です。
今後の宣言的設定
宣言的設定のジャーニーはまだ終わっていません。 私たちは現在、言語サポートの拡張に注力しており、これは開発者が好みのツールに関係なく宣言的アプローチの利点を活用できるようにするために重要です。
私たちはこれらの機能の開発と改良を続けるなかで、ユーザーフィードバックに強い関心を持っています。
現在の実装を試してみて、不足している機能、問題点、改善の余地があれば積極的に伝えてください。
この協力的なアプローチにより、開発の優先順位を決定するのに役立ち、私たちが構築するソリューションがコミュニティのニーズを真に満たすことを保証します。
CNCF Slackの#otel-config-fileチャンネルを使用して、フィードバックや質問を共有してください。
フィードバックを提供する意外にも、宣言的設定の成長に関与して貢献する方法は他にもあります。 各OpenTelemetry SDKには、その実装に特化したSpecial Interest Groups (SIGs)があります。 これらのSIGに参加することで、開発の現状を理解し、議論に参加し、貢献する機会を特定する直接的な手段が得られます。 コードの貢献、ドキュメントの改善、または単に経験を共有するなど、さまざまな貢献が宣言的設定エコシステムの発展に役立ちます。 あなたの積極的な参加は、現代のアプリケーション開発のための堅牢で多目的なツールセットを育成する鍵となります。
私たちはあなたを待っています！
追加リソース
宣言的設定に関する作業について詳しく知るには、以下の追加リソースを参照してください。