doca-telemetry-exporter

DOCA Telemetry Exporter

例

• 「DOCA アプリからカウンターを公開したい。」 — これは対象範囲内です。スキーマ、次にソースの順に進めてください。ここでは DTS を設定しないでください。
• 「イベントを報告するときに BAD_STATE が発生する。」 — 報告呼び出しを変更する前に、ライフサイクルの順序を確認してください。

手順

以下の読み込み順に従ってください。設定／公開／デバッグについてはタスク用のコンパニオンを開いてください。公開サーフェスについては機能用のコンパニオンを開いてください。すべてのコンパニオンファイルを開かないでください。

開始する場所： このスキルは、DOCA がすでにインストールされており、ユーザーがテレメトリーエクスポーターを実際に操作していることを前提としています。つまり、DOCA を使用するプログラムから外部のコンシューマーに構造化されたアプリケーションテレメトリー（カウンター／イベント）を送信する作業です。ユーザーが何かを実行したい場合（設定／ビルド／変更と再ビルド／実行／テスト／デバッグ）はタスク用のコンパニオンを開き、このインストール環境でエクスポーターが何を表現できるかについての質問には機能用のコンパニオンを開いてください。ユーザーがまだ DOCA をインストールしていない場合は、まず doca-setup/SKILL.md に案内してください。 ユーザーがこのライブラリと DOCA Telemetry Service（受信側）のどちらを使うべきか迷っている場合は、何かを設定する前に、機能用のコンパニオンにあるエクスポーターとサービスの使い分けに関するルールを確認してください。

このライブラリは DOCA Core コンテキストではありません。 エクスポーターには doca_ctx_start() はなく、doca_devinfo ごとの機能クエリーファミリーもありません（その doca_caps ダンプはスタブです）。ライフサイクルは schema_init → エクスポーターを設定 → 型を登録 → schema_start → source_create → source_start → 報告 → フラッシュ → 破棄、です。

このスキルが適切に回答できる質問の例

このスキルが回答するために構築された、テレメトリーエクスポーターに関する質問の種類と、それぞれの回答例です。エージェントは、重要なのは質問の種類であり、回答例はその一例にすぎないと捉えてください。

• 「どのライブラリを使えばよいですか――エクスポーターですか、それともテレメトリーサービスですか？」 — 回答例：「DOCA Flow プログラムから、1 秒あたりの処理済みパケット数カウンターを下流のコレクターに送信したいのですが、どの DOCA アーティファクトをリンクすればよいですか？」。これは ## Capabilities and modes の役割分担テーブルにあるエクスポーターとサービスの使い分けルール、およびパス選択の箇条書きで回答しています。どちらも、アプリケーションがリンクする送信側として doca-telemetry-exporter を示し、受信側／消費側についてはこのスキルの対象外としています。
• 「DOCA プログラムから最初の構造化イベントを出力するにはどうすればよいですか？」 — 回答例：「DOCA Flow アプリケーションから packets_processed イベントレコードを出力する」。## Capabilities and modes のオブジェクトテーブルにあるスキーマからソースまでのライフサイクルと、## configure + ## run のステップ 3 にあるワークフロー（バルク処理の前にファイル書き込みのスモークテストを実施）で回答しています。telemetry_export/ のサンプルから始めます。
• 「どの送信方法を使えばよいですか――型付きイベント、メトリクス、OTLP ログ、それとも NetFlow ですか？」 — 回答例：「インターフェースごとのラベル付きパケットカウンターと帯域幅ゲージが必要です」。## Capabilities and modes の送信方法テーブルで回答しています（この用途には Metrics API の _metrics_add_counter／_add_gauge と telemetry_export_metrics/ のサンプルが該当します）。さらに、## modify のサンプル一覧も参照してください。
• 「レポート呼び出しが DOCA_ERROR_BAD_STATE を返します。何が間違っていますか？」 — 回答例： 「最初の呼び出しで doca_telemetry_exporter_source_report が BAD_STATE を返します」。## Error taxonomy の BAD_STATE 行（ソースが開始されていない、または書き込み／フラッシュ時に OTLP コンテキストがない）と、## configure のライフサイクル順序で回答しています。この API に DOCA_ERROR_AGAIN と DOCA_ERROR_NOT_FOUND はありません。
• 「プログラムはレポートを送信しているのに、DTS／コレクターに何も届きません。何から確認すればよいですか？」 — 回答例：「レポートは成功を返しますが、DTS のログが空です」。## Safety policy の受信側を先に起動する手順と、## test のファイル書き込みスモークテストおよび check_ipc_status の手順で回答しています（ファイル書き込みで送信側を検証してから、IPC が CONNECTED で、受信側が起動していることを確認します）。
• 「エクスポーターがインストールされていて、トランスポートが稼働中であることを確認するにはどうすればよいですか？」 — 回答例：「DOCA 3.x のインストール環境にエクスポーターはありますか？また、DTS への IPC は実際に接続されていますか？」。## Version compatibility のバージョン互換性に関する補足で回答しています（doca-version/SKILL.md の検出手順への相互リンク）。また、## Capabilities and modes の正確なイントロスペクション規則に従います（デバイスの機能照会ではなく、doca_telemetry_exporter_check_ipc_status を使用します）。

対象読者

このスキルは、DOCA Telemetry Exporter を介して構造化テレメトリーを送信するアプリケーションを構築する外部開発者を対象としています。つまり、アプリケーションコードから doca_telemetry_exporter_* を直接（C/C++ で）呼び出すか、別の言語から FFI／バインディング経由で呼び出し、DOCA を利用するプログラムのカウンター、ゲージ、イベントを外部のテレメトリーコンシューマーに公開するユーザーです。このスキルは、DOCA Telemetry Exporter 自体に貢献する NVIDIA の開発者向けではありません。また、テレメトリーを受信／集約するサービスを構築するユーザー向けでもありません（DOCA Telemetry Service は別個の DOCA サービスであり、独自の公開ガイドがあります。doca-public-knowledge-map/SKILL.md から参照できます）。

言語の範囲。 DOCA Telemetry Exporter は、pkg-config モジュール名 doca-telemetry-exporter の C ライブラリとして提供されます。付属サンプルは C で記述されています。C および C++ のコンシューマーが標準的なケースであり、タスクの補足資料にある実例もこの利用経路を前提としています。その他の言語（Rust、Go、Python、…）のコンシューマーは、同じ *.so を FFI または言語固有のバインディング経由で利用します。その場合、このスキルでは、エクスポーターとサービスの違い、スキーマ → ソースのライフサイクル、トランスポートを基準にする（機能ではない）検出ルール、アプリと同じユーザーを使う権限ルール、バッファリングされたフラッシュベースの配信モデル、エラー分類に関する指針を言語に依存しない形で維持し、最終的にあらゆるラッパーが呼び出す権威あるインターフェイスとして公開 C ABI をエージェントに案内します。

このスキルを読み込むタイミング

ユーザーが言語を問わず、DOCA Telemetry Exporter を実際に操作している場合に、このスキルを読み込んでください。具体的には、次のような場合です。

• アプリケーションが送信するイベントについて doca_telemetry_exporter_schema を定義し（フィールド名とフィールド型）、イベントを公開する前にエクスポーターへ登録する場合。
• アプリケーション内の異なる論理テレメトリーソース（たとえば、ワーカースレッドごと、またはパイプラインステージごとに 1 つのソース）を表す doca_telemetry_exporter_source インスタンスを 1 つ以上作成する場合。
• アプリケーションが報告する内容に適した公開インターフェイス（型付き構造化イベント（_source_report）、不透明イベント（_source_opaque_report）、Metrics API（カウンター／ゲージ／ヒストグラム）、OTLP ログ、または NetFlow の姉妹 API）を選ぶ場合。
• エクスポーターのインストール状況とトランスポートの実態を確認する場合（このライブラリには doca_devinfo の機能クエリ群も doca_caps データもありません）。IPC の稼働状態には doca_telemetry_exporter_check_ipc_status、不透明ペイロードの上限には _source_get_opaque_report_max_data_size、設定値の取得には _schema_get_* ゲッターを使います。
• エクスポーター呼び出しから返された DOCA_ERROR_*（ライフサイクル順序に関する BAD_STATE、型／ラベルの不一致に関する INVALID_VALUE、NO_MEMORY、INITIALIZATION、バックエンドに関する UNKNOWN）と、アプリケーションに返される呼び出しごとのステータスをデバッグする場合。
• Telemetry Exporter と隣接する選択肢のどちらを使うか決める場合（標準出力や構造化ログの転送で十分なら doca_log、DOCA を認識しないシンクが必要なら Prometheus クライアントライブラリ、アプリに戻るリアルタイムイベントサブスクリプションが必要なら doca-comch/SKILL.md — エクスポーターは公開専用／一方向です）。
• エクスポーターの C ABI をラップする、C 以外のバインディング（Rust、Go、Python、…）を設計または拡張する場合。対象となるのは、エクスポーターとサービスの違い、スキーマ → ソースのライフサイクル、権限ポリシー、バッファリングされたフラッシュベースの配信モデル、ラッパーが遵守すべきトランスポートの調査方法とエラー規則です。

DOCA 全般の概要、DOCA 自体のインストール、テレメトリー受信サービス（DOCA Telemetry Service には独自の公開ガイドがあり、doca-public-knowledge-map/SKILL.md から参照できます）、またはエクスポーター以外のライブラリに関する質問では、このスキルを読み込まないでください。その場合は doca-public-knowledge-map/SKILL.md を使用してください。

このスキルが提供するもの

これは薄いローダーです。本体には、次にどのファイルを参照すべきか判断するために必要な案内だけを残しています。エクスポーター固有の実質的な情報は、次の2つの関連ファイルに記載されています。

• capabilities 関連ファイル — このインストール環境でエクスポーターが表現できる内容：エクスポーターとサービスの役割分担ルール、オブジェクトの系統（doca_telemetry_exporter_schema → _type/_field → _source とスキーマ → ソースのライフサイクル）、4つの公開方法（型付きイベント／不透明イベント／Metrics API／OTLP ログ）と NetFlow の関連 API、トランスポートを対象とするイントロスペクションルール（check_ipc_status、_get_opaque_report_max_data_size、_schema_get_* — doca_caps データなし、デバイスの cap-query なし）、エクスポーターのエラー分類（ライブラリ間で共通の DOCA_ERROR_* セットへのマッピング。このインターフェースには AGAIN も NOT_FOUND もないことを明記）、可観測性のインターフェース（呼び出しごとのステータス + IPC ステータス + ファイル書き込みの検査 + エンドツーエンドのシグナルとなる受信側）、アプリと同じユーザーに対する権限と、受信側を先に起動する段取りを適用する安全性ポリシー、そして doca_log と doca-comch を避けるパス選択ルール。
• tasks 関連ファイル — 対象となるエクスポーターの6つの動詞（configure、build、modify（その後に再ビルド）、run、test、debug）についての手順付きワークフロー。さらに、対象外の質問を適切な次のスキルに案内する Deferred task verbs ブロックもあります。

このスキルは、DOCA が標準の場所にすでにインストールされており、エクスポーターが設定されているテレメトリートランスポートに書き込めるユーザーとしてアプリケーションを実行でき、テレメトリーを受信するコンシューマーに接続できて、エクスポーターより先に起動しているホストを前提としています。DOCA のインストールは対象外です。その場合は doca-setup/SKILL.md を参照してください。また、テレメトリーを受信するサービスの設定や運用も対象外です。これは独自の公開ガイドを持つ別の DOCA サービスです。

このスキルが意図的に含めていないもの

このスキルはエージェント向けガイダンスであり、サンプルやテンプレートの一式ではありません。境界を明確に保つため、意図的に次の内容を含めていません。プルリクエストでも追加しないでください。

• 言語を問わず、あらかじめ作成された DOCA Telemetry Exporter アプリケーションのソースコード。 検証済みのエクスポーターソースコードは、同梱されている C サンプル /opt/mellanox/doca/samples/doca_telemetry_exporter/ です。エージェントの役割は、ユーザーをこれらのファイルに案内し、doca-programming-guide/SKILL.md にある汎用のサンプル変更ワークフローを使って最小限の差分で変更するよう指示することです。その際、## modify にあるエクスポーター固有の上書きルールを適用します。
• テレメトリーのコンシューマー／コレクター／受信サービス。 DOCA Telemetry Service は独自の公開ガイドを持つ別の DOCA サービスです。そちらへの案内は doca-public-knowledge-map/SKILL.md を通じて行います。このスキルが扱うのは公開側のみです。
• スキル内に置く単独のビルドマニフェスト（meson.build、CMakeLists.txt、Cargo.toml、…）。エージェントは、ユーザーのインストール済み DOCA を対象に、ユーザーのプロジェクトディレクトリ内でビルドマニフェストを作成します。pkg-config --modversion doca-telemetry-exporter が信頼できる情報源です。
• 種類を問わず、samples/、bindings/、reference/ のサブツリー。 このスキルのツリー内にモックや不完全な成果物を置くと、たとえ「reference」とラベル付けしていても誤解を招きます。ユーザーがビルド可能なものとして受け取ってしまうためです。

読み込み順

1. ユーザーの質問が対象範囲内であることを確認するため、まずこのスキルを読んでください。
2. エクスポーターとサービスのルール、オブジェクトの種類、スキーマ → ソースのライフサイクル、4 つの公開先 + NetFlow、トランスポートと機能のイントロスペクションに関するルール、エラー分類（注：AGAIN と NOT_FOUND はありません）、オブザーバビリティ、安全ポリシー、doca_log / comch を避けるパス選択ルールについては、機能に関する補足ドキュメントを参照してください。
3. 手順を追ったワークフロー（設定、ビルド、変更、再ビルド、実行、テスト、デバッグ）については、タスクに関する補足ドキュメントを参照してください。

どちらの補足ファイルも相互にリンクしており、 バージョンの正規ルールについては doca-version/SKILL.md に、 また、正しい回答が「エクスポーター固有のガイダンス」ではなく 「公開ドキュメントまたはインストール済みパッケージの レイアウトを調べる」である場合は doca-public-knowledge-map/SKILL.md にリンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — すべての公開 DOCA ドキュメントソースと、インストール済み DOCA パッケージのディスク上のレイアウトを示すルーティングテーブルです。エクスポーターの公開ガイド URL は https://docs.nvidia.com/doca/sdk/DOCA-Telemetry-Exporter/index.html です。 ディスク上のサンプルは /opt/mellanox/doca/samples/doca_telemetry_exporter/ にあります。DOCA Telemetry Service（レシーバー。ここでは対象外です）は、同じルーティングテーブルから参照できる別のガイドです。
• doca-setup/SKILL.md — 環境の準備、 インストールの確認、トランスポート側の到達性チェック、および公開 NGC DOCA コンテナーを使ったまだインストールしていない場合の手順です。このスキルでは、前提条件が満たされていること（特に、アプリケーションのユーザーがテレメトリトランスポートに書き込めること）を想定しています。
• doca-version/SKILL.md — DOCA のバージョンに関する正規ルールです。このスキルの ## Version compatibility では、4 要素の一致ルールと検出チェーンへの相互リンクに加えて、エクスポーター固有のオーバーレイルールを示しています。
• doca-structured-tools-contract/SKILL.md — バンドルの構造化ツールの優先順位ルール（検出／優先／フォールバック／報告）です。タスクに関する補足ドキュメントのコマンド付録は、この契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリに共通する一般的な DOCA プログラミングパターンです。正規の pkg-config + meson ビルドパターン、出荷済みサンプルを変更して最初のアプリを作る汎用ワークフロー、汎用ライフサイクル、ライブラリ横断的な DOCA_ERROR_* 分類、プログラム側のデバッグ順序を扱います。このスキルでは、これらにエクスポーター固有の内容を重ねて説明します。
• doca-comch/SKILL.md — アプリケーションへのリアルタイムイベントサブスクリプション（ホスト ↔ DPU のコントロールプレーンメッセージング）が必要な場合に適したプリミティブです。エクスポーターは公開のみの一方向です。サブスクリプションが実際の要件である場合、このスキルのパス選択ルールに従ってそちらを参照します。
• doca-debug/SKILL.md — 分野横断的なデバッグの手順（インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバー）です。エクスポーター固有のデバッグ（レシーバーが起動していない、ライフサイクル順序の BAD_STATE、型／ラベルの INVALID_VALUE、不透明パスが有効になっていない）は、この手順に重ねて適用します。