doca-telemetry-utils

DOCA Telemetry Utils

例

• 「この BlueField が実際に公開している診断カウンターは何ですか？」 — これは対象範囲内です。列挙してからプローブします。ここではコレクターアプリを起動しないでください。
• 「エクスポーターでは port_rx_bytes という名前なのに、下流で何も表示されません。」 — 名前を Data ID に変換し、エクスポーターを変更する前にデバイスごとの対応状況をプローブします。

クイックトリアージ：エクスポーターはデータを送信しているのに、コレクターには何も表示されない

1. doca_telemetry_utils get-counters：このリリースでカウンターが認識されていますか？
2. doca_telemetry_utils <counter>：プロパティのオプションを表示します。
3. doca_telemetry_utils <counter> <properties>：Data ID を解決します。
4. doca_telemetry_utils <device PCI> <counter> <properties>：このデバイスで「not supported」と表示される場合、エクスポーターはそのカウンターを黙って破棄します。そのカウンターをコミットしないでください。
5. doca_telemetry_utils <0x... Data ID>：通信上で取得した ID を逆引きします。
6. doca-version でホストと BlueField のリリースの組み合わせを確認します。
7. すべての手順で問題なく解決できる場合は、doca-telemetry の ## debug に引き継ぎます。

ツールの出力はそのまま引用してください。Data ID を手作業で作成しないでください。

手順

以下の読み込み順に従ってください。インストール／実行／テストについては、タスク用コンパニオンを開いてください。スキーマの検出とテレメトリーライブラリとの組み合わせについては、機能用コンパニオンを開いてください。コンパニオンファイルをすべて開かないでください。

最初に確認する項目： これは doca_telemetry_utils を呼び出すためのツールスキルです。doca_telemetry_utils は、カウンタースキーマの検出、カウンター名と Data ID の相互変換、デバイスごとのカウンター対応状況のプローブによって、DOCA Telemetry のエクスポーター／コレクターパイプラインをサポートする、文書化されたホスト側 CLI です。タスク用コンパニオンを開き、ホスト側の前提条件については ## install から、文書化されている3種類の呼び出し（列挙／名前→ID／ID→名前）については ## run から読み始めてください。質問が このツールはテレメトリースキーマについて実際に何を検出するのか、開発者側の doca-telemetry/SKILL.md やエクスポーターライブラリとどのように組み合わせるのか、エクスポーター設定をデバイスにコミットする前に、カウンターがそのデバイスに対応していることをどう確認するのか、または エクスポーターパイプラインがメトリックを黙って破棄するのはなぜか である場合は、機能用コンパニオンを開いてください。

このスキルの使い方。 このファイルを読んでから、質問に必要な ## <name> 見出しをコンパニオンファイル内で検索し、そのセクション全体を読んでください。回答はその内容に基づいて完結させ、記号とコマンドのみを引用してください。ドキュメントを閲覧せず、doca-public-knowledge-map にあるエントリーポイントを使用してください。環境の確認方法は、ユーザーの DOCA ホストで実行するコマンドとして提示してください。対象範囲外の依頼については、担当するスキルの名前を示して終了してください。

このスキルは、DOCA Telemetry デプロイメントにおける運用者側のサポートツールです。開発者側のコレクターライブラリ（doca-telemetry/SKILL.md）ではなく、開発者側のパブリッシャーライブラリ（doca-telemetry-exporter — doca-telemetry ## Related skills（doca-telemetry/SKILL.md#related-skills）を参照）でもなく、DOCA Telemetry Service（DTS）のデプロイメントガイドでもありません（doca-dts に案内してください）。 この3つはそれぞれ別の領域です。これらを混同することが、テレメトリーを使い始める際に最もよくある誤りです。

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

このスキルが回答するために作られた doca_telemetry_utils の質問クラスと、それぞれの具体例を示します。重要なのはクラスのほうで、具体例はその一例です。

• 「エクスポーターでは port_rx_bytes を出力していると表示されるのに、下流に何も届きません。何を間違えたのでしょうか？」 — 具体例：「エクスポーターの設定にカウンター名の文字列がありますが、コレクターにはその名前のイベントが届きません」。capabilities companion の名前 ↔ Data ID 変換手順と、tasks companion のデバイスごとのサポート確認プローブで回答します。エクスポーターが送信するのは名前ではなく Data ID です。設定内の名前が、デバイスでサポートされていない Data ID に解決されると、何も通知されずに破棄されます。
• 「この BlueField が実際に公開している DOCA 診断カウンターはどれですか？」 — 具体例：「エクスポーターの設定を書く前に、BlueField-3 のカウンタースキーマ全体を列挙したいです」。capabilities companion のスキーマ検出用呼び出しクラスで回答します（doca_telemetry_utils get-counters は、診断データのインターフェースで認識されているすべてのカウンター名を一覧表示します。デバイスごとのプローブと組み合わせて、サポート状況を確認してください）。
• 「キャプチャしたログに Data ID があります。これはどのカウンターですか？」 — 具体例：「下流のコンシューマーが Data ID: 0x1160000600030201 を出力しました。公開ガイドと照合できるよう、元に戻してください」。capabilities companion の逆引き呼び出しクラスと、tasks companion の ID にプロパティがエンコードされるルールで回答します（Data ID にはカウンターのプロパティの次元が含まれており、逆引きではそれらが報告されます）。
• 「このカウンターが持つプロパティの次元と、有効な値を教えてください」 — 具体例：「カウンターが pcie_link_write_stalled_time_* であることは分かっています。node／pcie_index／depth の意味と、デバイスで受け付けられる値を知りたいです」。capabilities companion のプロパティの次元の表と、引数なしでの <name> 呼び出しで回答します。後者では、ドキュメントに記載されたプロパティの選択肢、単位、単位固有の軸が出力されます。
• 「エクスポーターの設定に確定する前に、このデバイスがこのカウンターをサポートしているか確認できますか？」 — 具体例：「エクスポーターの設定を書く前に、node=1 の port_rx_bytes が PCIe アドレス X の BlueField で公開されていることを検証したいです」。capabilities companion のデバイスごとのサポート確認プローブ（<device PCI> <name> [properties]）と、tasks companion の確定前に検証するルールで回答します。
• 「インストール環境に doca_telemetry_utils はありますか？また、対応するバージョンの doca-telemetry ライブラリと組み合わされていますか？」 — 具体例：「エクスポーターが対象としている診断データのカウンターセットは、この DOCA バージョンで利用できますか？」。capabilities companion のバージョンオーバーレイで回答します。これは正規の doca-version/SKILL.md のチェーンに誘導し、さらにツールと doca-telemetry ライブラリのスキーマバージョンが一致する必要があるというルールを追加します。

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

ユーザーが実環境で doca_telemetry_utils を呼び出す場合、またはエージェントが呼び出す必要がある場合に、このスキルを読み込みます。環境には DOCA がインストールされており、スキーマの検出、デバイスごとのサポート検証、またはデータ ID の変換を必要とするエクスポーター／コレクターのパイプラインが存在していることが前提です。 具体的には、次のような場合です。

• 新しい DOCA Telemetry エクスポーター設定を作成する前に、カウンターのスキーマ全体を列挙する（get-counters）。
• 選択したカウンターとプロパティのセットが、対象デバイスで実際にサポートされているデータ ID に解決されることを、設定の確定前に検証する。
• 下流のコンシューマーから取得したデータ ID を逆引きして、カウンター名とプロパティを特定し、公開ガイドと照合する。
• *「エクスポーターは送信しているのに、コレクターが何も受信しない」*という報告をデバッグする（典型的なスキーマ不一致／未サポートのカウンターによる障害モード）。
• 構造化されたエクスポーター設定のベースラインの一部として、*「この BlueField とこの DOCA バージョンで検証済みのカウンターセット」*という成果物を作成する。
• DOCA のバージョンをまたいでエクスポーターのパイプラインを移行し、以前サポートされていた各カウンターが新しいバージョンでも問題なく解決されることを確認する。

一般的な DOCA の概要把握、コレクター／エクスポーターライブラリのプログラミング、DTS のデプロイ、または DOCA のインストールには、このスキルを読み込まないでください。その場合は、doca-public-knowledge-map/SKILL.md、doca-telemetry/SKILL.md、または doca-setup/SKILL.md を参照してください。

このスキルでできること

このスキルは薄いローダーです。実質的な内容は、次の 2 つの関連ファイルに記載されています。

• 機能の関連ファイル — doca_telemetry_utils が検出する内容と、開発者側の機能との連携方法を説明します。記載されている 3 種類の呼び出し（列挙／名前→ID／ID→名前）、プロパティ軸モデル（カウンターには node、pcie_index、depth などのプロパティ軸と、単位ごとの軸が含まれます）、任意のデバイスごとの機能プローブ（<device PCI> <name> は解決済みのカウンターをデバイスに対して実行します）、オペレーター側のサポート上の役割（開発者側のライブラリではありません。エクスポーター／コレクターの設定が実態に即したものになるようにします）、バージョンの対応関係（ツールと doca-telemetry ライブラリのスキーマバージョンの組み合わせ）、階層化されたエラー分類（インストール／解析／不明なカウンター／不明なデータ ID／プロパティの範囲外／デバイス非対応／バージョン／複数の層にまたがるエラー）、可観測性の対象（標準出力のみ）、安全性ポリシー（このツールは読み取り専用です。誤りがあってもクラッシュするのではなく、下流でメトリクスが黙って欠落します）。
• タスクの関連ファイル — 対象範囲内のタスク動詞に対応した、手順ごとのワークフローを説明します。install（ホスト側の DOCA と Telemetry コンポーネントの前提条件）、configure（軸の決定：呼び出しの種類、デバイス、カウンター）、build（インストールを参照 — バイナリは同梱されています）、modify（対応しない — バイナリにはパッチを適用せず、呼び出しと、解決済みのデータ ID を使用するエクスポーター／コレクター設定を変更します）、run（記載されている 3 種類の呼び出し）、test（選択したカウンターを、名前 → データ ID → デバイスごとのプローブ → エクスポーター設定 → コレクターでの受信の順に一貫して検証します）、debug（エラー分類に沿って確認します）、use（開発者側の doca-telemetry コレクター／エクスポーターのパイプラインへの引き継ぎ）、さらに Deferred task verbs ブロックも含まれます。

このスキルは、Telemetry コンポーネントを含む DOCA がすでにインストールされ、オペレーターが対象とする BlueField が DOCA から認識でき、解決済みのデータ ID を使用するエクスポーター／コレクターのパイプラインが、対応する doca-telemetry/SKILL.md のライブラリバージョンを基に作成中または作成済みであるホストを前提とします。

このスキルにあえて含めていないもの

このスキルはエージェント向けのガイダンスであり、サンプルやスクリプトのバンドルではありません。範囲を明確に保つため、意図的に以下を含めていません。また、プルリクエストで追加しないでください。

• 逐語的なカウンター一覧や Data ID テーブル。 カウンターのセットは DOCA のバージョンや BlueField の世代に応じて変化するため、このスキルに固定された一覧は、気付かないうちに古くなります。インストール済みのバイナリで実行する doca_telemetry_utils get-counters が信頼できる情報源です。
• 事前作成済みのエクスポーター／コレクター設定。 設定はインストール環境、デバイス、ユースケースによって異なるため、このスキルに同梱された設定は、異なるセットアップを使うオペレーターに誤解を与えるおそれがあります。
• DTS のデプロイ手順。 DTS は独自の公開ガイドを持つ独立した DOCA サービスです。doca-public-knowledge-map/SKILL.md を参照してください。このスキルは、DTS パイプラインが使用するカウンター名と ID を解決しますが、DTS の設定は行いません。
• ツールの出力を処理する、あらゆる言語のラッパー、パーサー、スクリプト。出力はシンプルなテキストの対応表です。これを使ってスクリプトを作成する場合は、最新のガイドを読み、インストール済みのバージョンに合わせてパーサーを作成してください。
• samples/ または reference/ サブツリー。 これは同梱 CLI 用の薄いローダーです。実質的な情報は、公開ページ、--help、および doca-telemetry/SKILL.md にあります。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内（テレメトリーパイプライン向けのオペレーター側サポートツールであり、開発者側のライブラリープログラミングではない）であることを確認してください。
2. 3 つの呼び出しクラス、プロパティ次元モデル、デバイスごとのサポート確認、バージョンオーバーレイ、エラー分類、可観測性の範囲、安全性ポリシーについては、機能に関するコンパニオンを参照してください。
3. ドキュメントに記載された呼び出しと、discover → resolve → validate → consume のワークフロー（install、configure、build、modify、run、test、debug、use）については、タスクに関するコンパニオンを参照してください。

関連スキル

• doca-telemetry/SKILL.md — このツールがオペレーターによる確認を支援するスキーマを備えた、開発者側のコレクターライブラリです。エクスポーターパイプラインのトリアージセッションでは、必ず両者を組み合わせてください。コレクターライブラリのスキルでは、コレクターとエクスポーターの使い分け、パブリッシャーとのスキーマ一致に関する契約、コンシューマーキューが満杯になった場合のバックプレッシャー規則について説明します。このツールの役割は、その契約のうち スキーマ の部分をオペレーター側から確認できるようにすることです。ライブラリとツールを混同することは、テレメトリーを初めて扱う際によくある間違いです。
• doca-public-knowledge-map/SKILL.md — docs.nvidia.com にある公開 DOCA Telemetry ガイドと DOCA Telemetry Service（DTS）ページへの案内、およびツールのディスク上のインストールレイアウトを説明します。
• doca-version/SKILL.md — DOCA のバージョン処理に関する正規のルールです。機能の補足ドキュメントにある ## Version compatibility セクションは、本文についてはこちらを参照する簡潔な補足であり、ツールと doca-telemetry ライブラリ間のスキーマバージョンの組み合わせに関するルールを追加しています。
• doca-setup/SKILL.md — 環境の準備、インストールの検証、そして公開 NGC DOCA コンテナーを使った まだインストールしていない場合 の手順を説明します。このスキルでは、前提条件が満たされていること（テレメトリーコンポーネントを含む DOCA がインストールされ、DOCA から BlueField が認識できること）を想定しています。
• doca-debug/SKILL.md — 分野横断的なデバッグ手順です。Telemetry-utils は、実行時レイヤーでカウンタースキーマとデバイスごとのサポート状況の実態を提示し、この手順を補います。エクスポーターパイプラインのリグレッションは、コレクターやネットワークの経路に手を加える前に、スキーマレイヤーで解決することがよくあります。
• doca-structured-tools-contract/SKILL.md — 構造化ヘルパーツールに関する、このバンドルの「検出 → 優先 → フォールバック → 報告」契約です。タスク補足ドキュメントのコマンド付録は、この契約に従います。
• doca-programming-guide/SKILL.md — あらゆるライブラリやツールのインターフェイスで共有される、一般的な DOCA プログラミングパターンです。関連するエラーが下流のコレクターやエクスポーターのコードで表面化した場合に、このツールのホスト側エラーレイヤーが上乗せする、ライブラリ間共通の DOCA_ERROR_* 分類も含まれます。