OpenTelemetry LLM 可観測性: Green の前にスキーマを固定する

OpenTelemetry LLM の可観測性は、テレメトリに宣言された意味がある場合にのみ役立ちます。 GenAI トレースを運用証拠として扱う前に、セマンティック規約のリビジョンを固定し、各操作の必須フィールドを検証し、未承認のコンテンツ キャプチャを拒否し、予期された操作が存在することを証明してから、鮮度、作業状態、および外部結果を個別に評価します。 2026 年 7 月にはその順序が重要になります。OpenTelemetry Web サイトは現在、GenAI の規約を次のように示しています。 専用リポジトリ。この記事で検査したソース リビジョンでは、 434c91dcc34ed038e3048c07720ddfed2c6bddfc 、リポジトリの README には依然としてスキーマ URL が TODO としてリストされています、生成クライアント スパン ドキュメントは 開発 とマークされます。 これは OpenTelemetry を避ける理由にはなりません。それが互換性を明示する理由です。 GenAI スパンを含むダッシュボードでは、古いプロデューサー、現在のコレクター、および 3 番目の属性シェイプ用に作成されたクエリを組み合わせることができます。安全なデフォルトは、コレクター構成の横にある、バージョン管理された小さな受け入れプロファイルです。 実際に運用している契約をピン留めする OpenTelemetry の GenAI リポジトリは、LLM クライアント、エージェント、ツールの実行、評価、メモリ、取得、および MCP。そのドキュメントの一部は YAML モデルから生成されており、ソースが検査可能でテスト可能であるため、これは貴重です。また、「OTel を使用している」ということは、互換性を主張するには曖昧すぎるということも意味します。 インストルメンテーションの展開ごとに 4 つの ID を記録します。 身元 例 なぜそれが重要なのか 規約ソース リポジトリとコミット SHA 確認した属性と操作コントラクトを定義します 計測パッケージ パッケージ名とバージョン スパンを発したものを特定します コレクターパイプライン 構成ダイジェストとデプロイメント ID 変換、フィルター、エクスポーターを識別します 契約の問い合わせ ダッシュボードまたはアラートのバージョン 判定が期待するフィールドを特定します たまたま到着したフィールドから規約の改訂を推測しないでください。これにより、静かなドリフトが明らかな互換性に変わります。プロデューサーがリビジョンを宣言できない場合、バッチを次のように分類します。 schema drift そのプロデューサーシェイプをテストして登録するまで。 これは、フレームワークネイティブのインスツルメンテーションと外部のインスツルメンテーションが共存する場合に特に重要です。 OpenTelemetry の エージェント可観測性ガイダンス ベイクイン計測器のメンテナンスのトレードオフについて説明し、外部パッケージがそれと衝突する可能性があることを警告しています。そうしないと、同じモデル コールが 2 回観察されたり、部分的なアップグレード後に 1 つのルートが古い規則のままになったりする可能性があります。 実際のルールは単純です。操作パスごとに 1 つの予期されるテレメトリ プロデューサー、ロールアウト コホートごとに 1 つの宣言された規約リビジョン、およびコホートが昇格される前に通過する必要があるカナリア トレースです。 完全なスキーマの前に小規模な運用プロファイルを検証する 完全なセマンティック規約バリデーターはリポジトリ モデルから生成できます。動作ゲートは小さい値から開始する必要があります。現在の決定に影響を与えるフィールドのみを適用し、より多くの操作を使用するにつれてプロファイルを拡張します。 固定されたリビジョンでは、 推論スパンテーブル マーク: gen ai.operation.name 必要に応じて; gen ai.provider.name 必要に応じて; error.type 操作がエラーで終了した場合に条件付きで要求される。 gen ai.request.model 利用可能な場合は条件付きで必要となります。 入力メッセージ、出力メッセージ、システム命令、およびオプトインとしてのツール定義。 これらの要件レベルは、「フィールドの有無」にフラット化されるべきではありません。エラースパンなし error.type 条約が期待する種類の証拠を失った。欠落しているリクエスト モデルは、利用できなかったときは正当である可能性があります。明示的なポリシーで収集が許可されていない限り、プロンプトと応答のコンテンツは存在しないままにする必要があります。 コンパニオン監査は、次のような狭いプロファイルを実装します。 コンテンツ チェックでは、属性 keys のみが調べられます。プロンプト テキスト、応答テキスト、システム命令、ツール引数の読み取りや保存は行いません。バリデーターを別の機密データ シンクに変えることなく、偶発的なオプトイン キャプチャを捕捉するにはこれで十分です。 ここには意図的な制限があります。このプロファイルは OpenTelemetry 仕様全体ではありません。運用の判定に使用される 1 つのレビュー可能な契約をテストします。上流のソースが変更された場合は、プロデューサーをアップグレードする前に、固定されたリビジョンを更新し、生成された定義を比較し、フィクスチャを調整して再実行します。 クリーンなトレースを解釈する前にカバレッジを監査する 適合スパンは依然として不完全な証拠である可能性があります。アプリケーションが期待していた場合 invoke agent , chat 、 そして execute tool ですが、トレースには最初の 2 つしか含まれていないため、正しい判断は次のようになります。 coverage gap 、健康的ではありません。 観察されたスパンからではなく、ワークフロー トポロジから予想される操作を構築します。 これにより、テレメトリ自体の完全性を定義する循環テストが回避されます。予期されるセットは、リリース マニフェスト、登録されたツール ルート、またはワークフロー定義から取得できます。これは、維持できるほど小さく、欠落しているインストルメンテーション パスを明らかにできるほど具体的である必要があります。 自動再試行には注意が必要です。現在のクライアント スパンの記述では、1 つの論理スパンが自動再試行を含む操作期間をカバーする必要があるとされています。アプリケーションは試行レベルのトランスポート スパンを保持することもできます。これら 2 つのレイヤーを重複したエージェント作業としてカウントしないでください。カバレッジが論理演算、試行、またはその両方で表現されるかを決定し、関係を明示します。 同様に、プロバイダー名は必ずしも最終的なモデル所有者であるとは限りません。この規約では、計測機器が透過的な上流プロバイダーではなく、プロキシまたはホスティング プラットフォームを認識している可能性があることに注意しています。扱う gen ai.provider.name 請求やモデルの出自に関するオラクルとしてではなく、文書化された範囲内のフォーマット識別子およびルーティング事実として。 スキーマ、健全性、結果を個別の判定として保持する スキーマとカバレッジを通過すると、トレースは正常性の決定を通知できるようになります。それ自体で決定するものではありません。 明示的な優先順位を使用します。 1. スキーマ ID — プロデューサは固定されたリビジョンと一致しますか? 2. スキーマの有効性 必須フィールドと条件フィールドは有効ですか? 3. コンテンツ ポリシー — このルートではオプトイン フィールドが許可されていますか? 4. カバレッジ — 予想される操作はすべて表されていますか? 5. 鮮度 — 証拠はワークフローにとって十分に新しいものですか? 6. 作業状態 — エージェントは動作中、待機中、停止中、不確実、または完了していますか? 7. 結果 — 約束された結果は目的地に存在しますか? この記事の 10 件の固定具は、これらの層を意図的に不便にしています。これには次のものが含まれます。 固定されていないプロデューサーとレガシープロデューサー。 推論スパンがありません gen ai.provider.name ; エラースパンがありません error.type ; 許可のないオプトインコンテンツキー。 ワークフローに期待されるツール スパンがありません。 結果の受領書のない完全なトレース。 検証済みだが古いトレース。 正当な人間の承認待ち。 新たにカバーされ、結果が検証された症例が 1 つあります。 以下を使用してアーティファクトを実行します。 実行された結果は、ちょうど 10 個のケースを分類しました。 の complete no receipt case はキー境界です。プロデューサーのリビジョンが一致します。そのスパンには、プロファイルに必要なフィールドが含まれています。予期されたエージェントとモデルの操作が存在します。テレメトリーは新鮮です。まだ戻ってくる unverified チケット、ファイル、デプロイメント、またはその他の約束された結果が存在することを証明する宛先の領収書がないためです。 の waiting for approval 場合は別の境界が保持されます。最近の適合スパンは、所有者と期限を伴う指名された人間による承認で停止します。それは失速ではありません。エージェントが失敗したかのようにオペレータをページングすると、有用な状態情報が破壊されてしまいます。 監査をリリースとインシデント管理に変える このテストを 3 つの時点で実行します。 インストルメンテーションをアップグレードする前に 、現在のリビジョン、パッケージのバージョン、コレクターのダイジェスト、および予想される操作を取得します。提案されたスタックに対して修正されたフィクスチャを再生します。変更された評決については、昇進前に説明する必要があります。 ロールアウト中 、登録されているすべてのモデル、エージェント、およびツールのルートを通じてコン​​テンツフリーのカナリアを発行します。各カナリアが一度到着し、期待されるプロデューサー ID を伝達し、運用プロファイルを通過し、鮮度ウィンドウ内で検索可能であることを確認します。 インシデント発生中 、4 つのレイヤーを「可観測性が壊れた」状態に折りたたむのではなく、保持します。スキーマ ドリフトでは、プロデューサーとクエリの調整が必要になります。カバレッジギャップがある場合は、計装の修理が必要になります。テレメトリが古い場合は、コレクターまたはエクスポーターの診断が必要です。 waiting 指定された所有者を呼び出します。 unverified 別のモデルの再試行ではなく、宛先チェックが必要です。 テレメトリ フィールドが変更されたためにエージェントを自動的に修復しないでください。慣例のドリフトにより、基礎となる研究を不健全にすることなく、証拠が不確実になる可能性があります。アクティブなリカバリを凍結し、失敗した証拠層を特定し、信頼性を回復する最小の可逆テストを使用します。 スキーマ プロファイルにも所有者が必要です。コミットを永久に固定することは安全ではありません。それは最終的な停滞です。レビューの頻度を割り当て、GenAI リポジトリを監視し、ピンを移動するときにフィクスチャの差分を要求します。 OpenTelemetry が安定した GenAI スキーマ URL を後で公開する場合は、プロデューサーとクエリがサポートするときにそれを採用しますが、カバレッジ、鮮度、待機、結果のチェックは独立したままにします。 Sidewisp は現在プライベートプレビュー段階です。 その公開エクスペリエンスは、早期アクセス Web サイトとインタラクティブなデモンストレーションです。実稼働エージェントの健全性収集、ホスト アダプター、およびリカバリは、現在の Web サイト リポジトリには同梱されていません。製品の方向性は、OpenTelemetry コレクター、トレース バックエンド、自律型フィクサーではなく、既存のランタイムを中心としたヘルス レイヤーです。 リビジョンに固定された証拠と個別の結果検証が検出する必要がある障害と一致する場合、次のことが可能です。 Sidewisp プライベート プレビューに参加する そして、運用しているエージェントのランタイムとテレメトリ パスについて説明します。