doca-telemetry

DOCA Telemetry

例

• 「エクスポーターアプリが公開するイベントを受信する、別のプログラムを作ってください。」 DOCA ライブラリにエクスポーターイベントを消費するものはありません。また、このスキルもそのようなライブラリではありません。doca-telemetry はデバイスのハードウェアカウンターを読み取ります。アプリは公開に doca-telemetry-exporter をリンクします。受信側は IPC 経由の DOCA Telemetry Service（doca-dts）、またはローカルでのスモークテスト用のエクスポーターのファイル出力です。消費 API やコレクター API を捏造しないでください。その後は、公開するアプリがスキーマを管理します。doca_telemetry_exporter_check_ipc_status で IPC パスを確認します。大量処理の前に、フィールド値を保持したまま 1 件のイベントをファイル出力でスモークテストします。報告が追いつかない場合は、ホットパスでドロップまたは集約し、決してブロックしないでください。

• 「BlueField アプリから PCC カウンターを読み取るには？」 — これは対象範囲内です。ドメインごとの Telemetry リーダーを使用してください。ここでは DTS やエクスポーターを立ち上げないでください。手順は、デバイス上で doca_telemetry_pcc_cap_is_supported を呼び出し、オープン済みの doca_dev に PCC コンテキストを作成し（representor の場合は doca_telemetry_pcc_rep_create）、開始してから、doca_telemetry_pcc_get_counters で一度読み取り、最後に停止して破棄します。開始前に読み取ると DOCA_ERROR_BAD_STATE が返されます。

• 「DPA カウンターのエクスポートをサンプリングしてください。」 — doca_telemetry_dpa の読み取りを使用してください。これらのサンプルの公開はエクスポーターのスキルの対象です。

手順

以下の読み込み順序に従ってください。設定／読み取り／デバッグにはタスク用のコンパニオンを開いてください。ドメインごとのリーダーについては、機能用のコンパニオンを開いてください。すべてのコンパニオンファイルを開かないでください。

最初に確認する内容： このスキルでは、DOCA がすでにインストールされており、ユーザーがハードウェアカウンターリーダーを実際に扱う作業をしていることを前提とします。つまり、doca_dev に対してドメインごとの doca_telemetry_<domain> コンテキストを開き、そのドメインの最新のハードウェアカウンタースナップショットを読み取る作業です。このライブラリは、DOCA Telemetry のカウンターリーダー側です。NetFlow／IPFIX コレクターでも、汎用スキーマイベントのコンシューマーでもありません（バンドルでは以前そのように説明されていましたが、誤りでした。公開ヘッダーには NetFlow／IPFIX／ローカルソケットのトランスポート機能はありません）。 ユーザーが何かを実行（設定／ビルド／変更／実行／テスト／デバッグ）したい場合はタスク用のコンパニオンを開いてください。このインストール環境でデバイスがどのハードウェアカウンタードメイン（PCC、DPA、DIAG、ADP_RETX、PHY、PCI）を読み取れるかという質問には、機能用のコンパニオンを開いてください。ユーザーがまだ DOCA をインストールしていない場合は、最初に doca-setup/SKILL.md に案内してください。ユーザーがこのライブラリ（doca_dev 上の HW カウンターリーダー）と doca-telemetry-exporter/SKILL.md（構造化テレメトリ／ラベル付きメトリクス／OTLP ログを公開する、別ライブラリであるパブリッシャー／エクスポート側）のどちらを求めているのか分からない場合は、何かを設定する前に、機能用のコンパニオンにあるリーダーとエクスポーターの役割分担を読んでください。この 2 つを混同することが、このスキルで最初のアプリを作成する際の重大な失敗につながります。ユーザーが**導入済みの DOCA Telemetry Service（DTS）**について尋ねている場合は、doca-dts に案内してください。

対象読者

このスキルの対象は、doca_dev からハードウェアカウンターを読み取るアプリケーションを構築する 外部の開発者 です。読み取りには、6 つのドメイン別 DOCA Telemetry リーダーライブラリ（doca_telemetry_pcc / _dpa / _diag / _adp_retx / _phy / _pci）のうち 1 つ以上を使用します。つまり、アプリケーションコードから doca_telemetry_<domain>_*（C/C++ から直接、または他の言語から FFI / バインディング経由で）を呼び出し、doca_dev 上のドメイン別コンテキストを開き、ドメイン別のサンプルウィンドウを設定して、そのドメインのハードウェアカウンターのスナップショットを読み取るユーザーが対象です。このスキルは、DOCA Telemetry 自体に貢献する NVIDIA の開発者を対象としていません。また、公開／エクスポート 側を実装するユーザーも対象外です。そちらについては、別のライブラリと別のスキルである doca-telemetry-exporter/SKILL.md を参照してください。

言語の範囲。 DOCA Telemetry のドメイン別リーダーライブラリは、pkg-config モジュール名 doca-telemetry の C インターフェースとして提供されています。付属サンプルは C で記述されています。C および C++ のリーダーが標準的なケースであり、タスク用の補足資料にある実例もこの経路を前提としています。他の言語のリーダー（Rust、Go、Python、…）は、FFI または言語固有のバインディングを介して同じ *.so を利用します。その場合、このスキルでは、リーダーとエクスポーターの区別、ドメイン別の機能照会を最初に行う原則、doca_dev 上のドメイン別 DOCA Core ライフサイクル、サンプルウィンドウの取り扱い、エラー分類に関する指針を言語に依存しない形で維持し、最終的にすべてのラッパーが呼び出す公開ドメイン別 C ABI を正式なインターフェースとしてエージェントに案内します。

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

ユーザーが、言語を問わず、DOCA Telemetry の hardware-counter-reader を実際に使って作業している場合に、このスキルを読み込みます。具体的には、次のような場合です。

• ユーザーが必要としているカウンターに適したドメイン別ヘッダーを選択する場合（Programmable Congestion Control カウンターには doca_telemetry_pcc.h、DPA カウンターには _dpa.h、汎用デバイス診断カウンターには _diag.h、ADP 再送カウンターには _adp_retx.h、物理層カウンターには _phy.h、PCI／PCIe カウンターには _pci.h を使用）、さらにドメイン別の _cap_is_supported(devinfo) クエリでデバイスが対応していることを確認する場合。ただし、_pci には単一の _cap_is_supported がなく、代わりに doca_telemetry_pci_cap_management_info_is_supported／_cap_perf_counters_1_is_supported のような機能別のケイパビリティが公開されています。
• doca_dev 上でドメイン別の doca_telemetry_<domain> コンテキストを開き、ドメイン別のライフサイクル（doca_telemetry_<domain>_create(dev) → ドメイン別セッター → doca_telemetry_<domain>_start）を実行し、ドメイン別のサンプルウィンドウを設定して、そのドメインのハードウェアカウンターのスナップショットを読み取る場合。この API はドメイン別の _create／_start を使うものであり、汎用の doca_ctx_* プログレスエンジンのライフサイクルではない点に注意してください。
• カウンターファミリーが利用可能だと決めつける前に、デバイスとライブラリのケイパビリティを確認する場合。doca_telemetry_<domain>_cap_is_supported を使うのは pcc、dpa、diag、adp_retx、phy のみです。PCI では、対応する機能別の doca_telemetry_pci_cap_*_is_supported クエリを使用します。
• カウンター読み取り時のドメイン別 DOCA_ERROR_* 戻り値（ライフサイクル、デバイスが当該ドメインをサポートしていない場合、スナップショットの準備ができていないことを示すドメイン別 AGAIN、権限／ドライバー）と、アプリケーションに返される読み取りごとのステータスを処理する場合。
• DOCA Telemetry（ハードウェアカウンターの READER）と、隣接する別の選択肢を比較する場合。カウンター値の PUBLISH／EXPORT（OTLP／Prometheus／ラベル付きメトリクス）が実際の目的なら doca-telemetry-exporter/SKILL.md、通常の構造化 stdout ロギングで十分なら doca-log、カウンターのソースが DOCA 以外のプログラムなら汎用の Prometheus／OpenTelemetry クライアントライブラリ、すぐに使える集約機能が必要なら DOCA Telemetry Service（doca-dts）を使用します。
• ドメイン別リーダーの C ABI をラップする、C 以外のバインディング（Rust、Go、Python など）を設計または拡張する場合。リーダーとエクスポーターの違い、ドメイン別のケイパビリティクエリを先に行うルール、ドメイン別の doca_dev ライフサイクル、サンプルウィンドウの扱い、ラッパーが守るべきエラー規則が対象です。

DOCA の一般的な概要、DOCA 自体のインストール、公開／エクスポート側（専用のスキルは doca-telemetry-exporter/SKILL.md にあります）、DOCA Telemetry Service（doca-dts）、またはリーダー以外のライブラリに関する質問では、このスキルを読み込まないでください。 その場合は doca-public-knowledge-map/SKILL.md を使用してください。

このスキルで提供する内容

これは薄いローダーです。本文には、次に読むべきファイルを選ぶために必要な概要だけを記載しています。ハードウェアカウンターリーダーに関する具体的な内容は、補足ファイル2つに記載されています。

• 機能補足ファイル — このインストール環境でドメインごとのリーダーが扱える内容を説明します。リーダーとエクスポーターの役割分担ルール、同梱されている6つのサブライブラリ（doca_telemetry_pcc / _dpa / _diag / _adp_retx / _phy / _pci）と各ライブラリが公開するカウンターファミリー、doca_dev 上でのドメインごとの DOCA Core ライフサイクル、PCC / DPA / DIAG / ADP_RETX / PHY のドメインレベルの機能照会と、PCI の機能ごとの機能照会、リーダーのエラー分類（共通ライブラリ間の DOCA_ERROR_* セットへの対応付けと、「NOT_SUPPORTED はこのデバイスで当該ドメインが公開されていない」というルール、および「AGAIN はスナップショットがまだ準備できていない」というルールを明記）、可観測性の対象（読み取りごとのステータスと、構成時のドメインごとの機能照会スナップショット）、機能照会の結果に基づいてドメインごとの読み取りを制御する安全ポリシー、doca-telemetry-exporter/SKILL.md、doca-log、およびスタンドアロンの Prometheus / OpenTelemetry / DTS との使い分けルールを説明します。
• タスク補足ファイル — 対象となる6つのリーダー操作（configure、build、modify、run、test、debug）の手順を説明します。また、対象外の質問を適切な次のスキルに案内する「Deferred task verbs」ブロックもあります。

このスキルは、DOCA が標準の場所にすでにインストールされており、ターゲットの BlueField DPU または ConnectX NIC が利用可能なホストを前提とします。## run ワークフローでは、対応する doca_dev を開き、ドメインごとの機能照会が DOCA_SUCCESS を返す必要があります。DOCA のインストール方法は扱いません。インストール手順は doca-setup/SKILL.md を参照してください。また、公開やエクスポートの側の実装も扱いません。そちらは doca-telemetry-exporter/SKILL.md を参照してください。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内であることを確認してください（具体的には、ユーザーが doca_dev 上でドメインごとのリーダー API を介してドメインごとのハードウェアカウンターを読み取りたいのかを確認します。カウンターを公開したい場合は doca-telemetry-exporter/SKILL.md、DTS をデプロイしたい場合は doca-dts、NetFlow / IPFIX コレクターを立ち上げたい場合は、このライブラリではその機能を公開していないため対象外です）。
2. リーダーとエクスポーターの使い分けルール、ドメインごとの6つのサブライブラリ、doca_dev 上でのドメインごとの DOCA Core ライフサイクル、ドメインごとの機能照会、エラー分類（「NOT_SUPPORTED はこのデバイスで当該ドメインが公開されていない」というルール、および「AGAIN はスナップショットがまだ準備できていない」というルールを含む）、可観測性、安全ポリシー、使い分けルールについては、機能補足ファイルを参照してください。
3. configure、build、modify、run、test、debug の手順については、タスク補足ファイルを参照してください。

どちらの補足ファイルからも、もう一方の補足ファイル、バージョンの扱いに関する正式なルールを記載した doca-version/SKILL.md、および答えが「リーダー固有のガイダンス」ではなく「公開ドキュメントまたはインストール済みパッケージの構成を調べる」である場合に参照する doca-public-knowledge-map/SKILL.md にリンクしています。

関連スキル

• doca-telemetry-exporter/SKILL.md — 公開／エクスポート側です。このスキル（ドメイン別ハードウェアカウンターリーダー）と doca-telemetry-exporter（アプリケーション側のラベル付きメトリクス／OTLP ログパブリッシャー）は、異なる問題を解決する別々のライブラリです。パブリッシャーとコレクターのペアを構成するものではありません（ここにはコレクターの転送インターフェイスがありません）。監視パイプラインにカウンターを送信したいアプリケーションはエクスポーターをリンクし、doca_dev からハードウェアカウンターを読み取りたいアプリケーションはこのスキルをリンクします。ユーザーのアプリに誤ったライブラリを組み込むことは、両スキルにおける最も多い初回アプリの失敗原因です。これは、エージェントがコードレベルの案内をする前に明示すべき重要なルールです。
• doca-public-knowledge-map/SKILL.md — すべての公開 DOCA ドキュメントソースと、インストール済み DOCA パッケージのディスク上のレイアウトを示すルーティングテーブルです。ドメイン別リーダーの公開ガイド URL は https://docs.nvidia.com/doca/sdk/DOCA-Telemetry/index.html です（パブリッシャーのガイド https://docs.nvidia.com/doca/sdk/DOCA-Telemetry-Exporter/index.html とは異なります）。ディスク上のサンプルは /opt/mellanox/doca/samples/doca_telemetry/ 以下にあります。DOCA Telemetry Service（DTS）には、doca-dts という専用スキルがあります。
• doca-setup/SKILL.md — 環境の準備、 インストールの検証、および公開 NGC DOCA コンテナーを使った まだインストールしていない場合 の手順です。このスキルは、前提条件が満たされていることを想定しています（特に、doca_dev がオープンされており、ユーザーが読み取りたいドメイン別ライブラリについて doca_telemetry_<domain>_cap_is_supported(devinfo) が DOCA_SUCCESS を返すこと）。
• doca-version/SKILL.md — DOCA のバージョン処理に関する標準ルールです。このスキルのバージョン互換性オーバーレイでは、4 方向の一致ルールと検出チェーンを相互参照し、さらにドメイン別リーダー向けのオーバーレイを追加しています（各ドメイン別ライブラリのカウンターセットは DOCA のリリースごとに増える可能性があります。まず cap-query を行い、その後に読み取ります）。
• doca-structured-tools-contract/SKILL.md — バンドルの構造化ツール優先ルール（検出／優先／フォールバック／報告）です。タスク補足資料のコマンド付録は、この契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリで共通する、一般的な DOCA プログラミングパターンです。標準の pkg-config + meson ビルドパターン、提供済みサンプルを変更する汎用の初回アプリワークフロー、共通のライフサイクル、ライブラリ間で共通する DOCA_ERROR_* の分類、プログラム側のデバッグ手順が含まれます。このスキルは、その上にドメイン別リーダー固有の内容を重ねます。
• doca-log — ユーザーが構造化されたハードウェアカウンタースナップショットではなく、自作プログラムからの通常の構造化標準出力ログを求めている場合に適した基本機能です。通常のログにはドメイン別リーダーの cap-query 手順は不要です。ログ転送が実際の要件である場合、このスキルの経路選択ルールによってそちらに案内されます。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／実行時／プログラム／ドライバーを横断するデバッグ手順です。ドメイン別リーダー固有のデバッグ（デバイスがドメインをサポートしていない、スナップショットの準備がまだできていない、サンプル期間が短すぎる、読み取り前に cap-query を忘れている）は、この手順に重ねて適用されます。