nemo-relay-plugin-observability

可観測性プラグインを設定する

まず、組み込みの可観測性プラグインで管理するエクスポーターを1つ設定します。 これは再利用可能なプロセス設定のデフォルトであり、Relay が取得したアクティビティを可視化できるため、ほとんどのユーザーにとって最初に使うのに最適なプラグインです。 追加のテレメトリー送信先を重ねる前に、出力を1つ選んで動作を確認してください。

テスト、スクリプト、またはアプリケーションで登録名、収集期間、フラッシュのタイミングを直接制御する必要がある場合に限り、手動のサブスクライバー API またはエクスポーター API を使用してください。 どちらの方法も同じ正規イベントストリームを使用します。

Relay のバージョンを選択する

設定やバインディング API を提案する前に、アプリケーションが NeMo Relay 0.6 と 0.7 のどちらを使用しているか確認してください。 インストール済みパッケージのバージョン、ロックファイル、またはマニフェストを優先して確認します。 バージョンを特定できない場合はユーザーに尋ね、1つの例の中で両方の API を混在させないでください。

• 0.6 では可観測性設定のバージョン2を使用します。OpenTelemetry と OpenInference は個別のエクスポーターで、それぞれ OpenTelemetryConfig / OpenTelemetrySubscriber と OpenInferenceConfig / OpenInferenceSubscriber を使用します。
• 0.7 では可観測性設定のバージョン3を使用します。型付きの OpenTelemetry エクスポーター1つで、full、gen_ai、openinference の各プロジェクションを提供します。

出力を選択する

ユーザーが直ちに確認したい対象に最も適した出力を選択します。

• コンソールまたはカスタムイベント処理 短時間のインプロセス確認には、手動のサブスクライバーを使用します。
• 生の正規ライフサイクルイベント ATOF JSONL を使用します。references/atof.md を参照してください。
• 移植可能な実行トラジェクトリー ATIF を使用します。references/atif.md を参照してください。
• OTLP トレーシング 0.6 では、個別の OpenTelemetry または OpenInference エクスポーターを選択します。0.7 では、 型付きの OpenTelemetry エンドポイント（full、gen_ai、または openinference）を選択します。references/opentelemetry.md と、 OpenInference 対応バックエンドの場合は references/openinference.md を参照してください。

まず出力を1つ選んで検証してから、別の出力を追加してください。 ATOF は、変換を最小限に抑えつつ生のイベントストリームを保持するため、ローカルでの最初の動作確認に適しています。 最初の動作確認には、合成した機密性のないペイロードを使用してください。 本番のペイロードをエクスポーターに渡す前にサニタイズを追加して検証し、エクスポーターの検証中にイベントレコード全体を表示しないでください。

組み込みイベントおよびサブスクライバーモデル

キャプチャとエクスポートの関係を説明するときは、このモデルを使用してください。

• NeMo Relay は、スコープ、マーク、管理対象のツール呼び出し、管理対象の LLM 呼び出し、ミドルウェア、手動のライフサイクル API から、単一の正規イベントストリームを生成します。
• サブスクライバーは、イベントモデルを定義せずにイベントを消費します。複数のサブスクライバーが同じストリームを監視し、ロギング、エクスポート、分析、診断に利用できます。
• グローバルサブスクライバーは、削除されるまでプロセス全体で有効です。
• スコープローカルサブスクライバーは、1 つのアクティブなスコープに属し、そのスコープが閉じると破棄されます。
• プラグインによってインストールされるサブスクライバーは、再利用可能で、設定駆動型のランタイムコンポーネントです。
• エクスポーター指向のサブスクライバーは、未加工の ATOF を保持するか、イベントストリームを ATIF またはバージョンに適した OpenTelemetry/OpenInference 形式に変換します。
• 呼び出しで管理ヘルパーが使用される場合、または手動のライフサイクルパラメーターで入力フィールドと出力フィールドが指定される場合、イベントペイロードにはガードレール処理後のサニタイズ済み入力と出力が反映されます。
• LLM アノテーションは、次の鮮度ルールに従います。
  • 各所有元エージェントスコープではアノテーションが新規に開始され、compaction マークによって更新されます。
  • その後最初に開始される LLM ではアノテーション履歴全体が保持されます。以降の開始では、システム指示、最新のユーザーメッセージ、およびその後に続くすべてのアシスタントまたはツールのメッセージが保持されます。
  • リクエストコーデックがアノテーションを提供する場合、Relay は、プロバイダーの実行を変更せずに、プロバイダー形式のイベント入力に同じイベント専用の投影を適用します。
• イベントフィールドには、ATOF の data フィールドによる意味的な入力と出力、model_name や tool_call_id などの型付きプロファイルデータ、およびプロセス内のサブスクライバーとエクスポーター向けの、コーデックが提供するアノテーション付き LLM リクエスト／レスポンスデータが含まれます。
• ファーストクラスのスキルツールと、完全な SKILL.md を読み取るリクエストは、ツールスパンの下に skill.load マークを自動的に出力します。ペイロードには skill_name のみが含まれます。メタデータには読み込み元とツール名が記録されます。一部のみの読み込みは対象外で、曖昧なスラッシュコマンドの展開には別の skill.load.inferred という名前が使用されます。ツールの実行が後で失敗しても、先行して出力されたマークは保持されます。

共通のライフサイクル

1. エクスポーターまたはサブスクライバーを作成します。
2. 該当するスコープ内の作業を開始する前に、一意の名前で登録します。
3. NeMo Relay によって計装された作業をスコープ内で実行します。
4. エクスポーター固有のリファレンスに記載された順序に従って、フラッシュして登録を解除します。
5. プロセスまたはサブシステムの処理が完了したら、シャットダウンします。

バインディング名

選択した言語バインディングと Relay のバージョンでエクスポートされる名前を使用してください。

• Python 0.6：nemo_relay.subscribers.register(...)、AtofExporter、 AtifExporter、OpenTelemetrySubscriber、OpenInferenceSubscriber
• Python 0.7：同じ登録関数とファイルエクスポーターに加えて、 3 つすべての型付き投影に対応する OpenTelemetrySubscriber
• Node.js は、ルートエクスポートを通じて同じ 0.6/0.7 の区分に従います
• Rust：nemo_relay::api::subscriber と nemo_relay::observability::*
• Go：ソース優先のラッパーで、同等の登録、エクスポーター、サブスクライバーの ライフサイクルメソッドが公開されます

リファレンスを読み込む場合

選択した出力に必要なリファレンスのみを読み込んでください。

• ローカルデバッグやオフラインでの調査に使用する未加工の JSONL イベントには、references/atof.md を読み込みます。
• ATIF の軌跡には、references/atif.md を読み込みます。
• OTLP/OpenTelemetry トレースには、references/opentelemetry.md を読み込みます。
• 単独の 0.6 OpenInference エクスポーター、または 0.7 の openinference OpenTelemetry 投影には、references/openinference.md を読み込みます。

別のスキルを使用する場合

タスクが隣接するワークフローに属する場合は、別のスキルを選択してください。

• サブスクライバーベースのエクスポート動作を再利用可能なプラグインとしてパッケージ化するには、nemo-relay-plugin-build を使用します。
• スコープ、ツール呼び出し、LLM 呼び出しのいずれも計装されていない場合は、nemo-relay-get-started または nemo-relay-instrument-calls を使用します。
• テレメトリが欠落する問題を診断するには、nemo-relay-debug-runtime-integration を使用します。

関連スキル

隣接するワークフローでは、以下のスキルを使用します。

• nemo-relay-instrument-calls でアプリケーション呼び出しを計測します。
• nemo-relay-instrument-typed-wrappers で型付きラッパーを追加します。
• nemo-relay-plugin-build で再利用可能な動作をパッケージ化します。
• nemo-relay-debug-runtime-integration で欠落しているイベントを診断します。