jetson-diagnostic

Jetson 診断

稼働中の Jetson デバイスを、エージェントが使いやすい統一された視点から確認できます。tegrastats、jtop、procrank、/sys/kernel/debug/nvmap、nvpmodel、free、swapon、df、systemctl list-units のどれが情報のどの部分を示すのかを覚えておく必要がなくなります。

目的

Jetson ホストの読み取り専用のヘルススナップショットを取得し、エージェントが推測ではなくライブデータに基づいて、デバイスの識別情報、メモリ、GPU、温度、電力、ストレージ、サービスの状態に関する質問に回答できるようにします。

使用するタイミング

次のような質問があった場合に有効化します。

• 「これはどの Jetson ですか？SKU は何ですか？メモリはどれくらいありますか？」
• 「今、この Jetson では何が実行されていますか？」
• 「Jetson の動作が遅い／熱い／メモリ不足になるのはなぜですか？」
• 「GPU／CPU／電力の使用状況をスナップショットで確認してください。」
• 「tegrastats の出力は何を意味しますか？」
• 「停止できそうな実行中のサービスはどれですか？」
• ユーザーが jetson-memory-audit、jetson-headless-mode、jetson-inference-mem-tune、jetson-llm-benchmark、jetson-llm-serve、または jetson-package をインストールしており、実行前の基準値を測定する必要がある場合。

このスキルは、電力モードの変更、キャッシュの解放、サービスの停止、パッケージのインストール、モデルの配信、推論フラグの調整には使用しないでください。観測した状態を報告した後、操作を行うスキルに引き継いでください。

前提条件

• Jetson ホスト上、またはホストから Jetson のシステムパスとプロセスデータを参照できるサンドボックス／コンテナ内で実行してください。

利用可能なスクリプト

スクリプト	目的	引数
scripts/snapshot.sh	デバイス識別情報、メモリ、GPU、温度、電力、ディスク、上位プロセス、候補となるサービスをまとめた JSON スナップショットを出力します。	--human、--tegra-secs N、--top-procs N。
scripts/mem_summary.sh	RAM／GPU／スワップの概要を簡潔で読みやすい形式で出力します。	--short、--watch、--interval N。
scripts/detect_jetson.sh	このリポジトリ向けの標準 Jetson SKU／世代／製品ラインのフィールドをエクスポートまたは出力します。	引数なし。

エージェントのランタイムが run_script に対応している場合は、それを使って scripts/snapshot.sh または scripts/mem_summary.sh を実行し、返された出力を要約してください。それ以外の場合は、リポジトリのルートから bash でスクリプトを実行してください。

手順

1. 一括 JSON 表示を取得するには、scripts/snapshot.sh を実行します（通常はこちらを使用します）。
2. 人が読みやすい形式でメモリの概要をすばやく確認するには、scripts/mem_summary.sh を実行します。
3. ユーザーが貼り付けた特定の tegrastats の行を説明するには、references/tegrastats-fields.md を参照してください。
4. NvMap クライアントの出力を説明するには、references/nvmap-clients.md を参照してください。

レポートの指針

デバイスの状態を要約する前に、該当するヘルパースクリプトを実行し、そのスクリプトが返したフィールドのみを報告してください。ランタイムによって直接実行がブロックされる場合は、ファイルに chmod を試すのではなく、bash {baseDir}/scripts/<script-name> で実行してください。

• 「これはどの Jetson ですか」という質問には、product_model または sku、variant、l4t_version、mem_total_gb を引用してください。
• 「動作が遅く、熱い」という質問には、snapshot.sh を実行し、症状の両面を要約してください。熱については thermal_c、負荷については top_processes、gpu_processes、nvmap.top_clients、または gpu_source を示します。最後に、jetson-memory-audit、jetson-headless-mode、jetson-inference-mem-tune など、具体的な引き継ぎ先を示してください。
• 「どのプロセスがメモリを使用していますか」という質問には、snapshot.sh を実行し、先頭のプロセスを pid <number>、cmd、およびその pss_kb／MiB 値で示してください。NvMap GPU メモリが関連する指標である場合は、gpu_source と、nvmap.top_clients または gpu_processes の先頭のエントリーも引用してください。

エージェントのランタイムが、このスキルディレクトリを基準としたヘルパースクリプトを自動実行しない場合は、AgentSkills の {baseDir} プレースホルダーを使ってスクリプトのパスを解決してください。

{baseDir}/scripts/snapshot.sh
{baseDir}/scripts/mem_summary.sh

ランタイムがスキルを呼び出し可能なツールとして明示的に登録していない限り、jetson-diagnostic をツール名として呼び出さないでください。Agent Skills は通常、直接呼び出せるツール関数ではなく、指示とファイルで構成されています。

すべてのスクリプトは、正規のプラットフォーム検出スクリプト skills/jetson-diagnostic/scripts/detect_jetson.sh を読み込みます（JETSON_SKU、JETSON_GENERATION、JETSON_PRODUCT_LINE、JETSON_VARIANT、JETSON_MEM_GB、JETSON_L4T_VERSION、JETSON_PRODUCT_MODEL をエクスポートします）。ほかのスキルでも、Jetson の識別ロジックを重複させず、この検出スクリプトを読み込むことができます。プラットフォーム外では、修正方法を示すメッセージとともに終了コード 2 で終了します。

制限事項

• このスキルファイルを確認できても、Jetson ホストのハードウェアにアクセスできるとは限りません。NemoClaw／OpenClaw のサンドボックス内で /proc/device-tree/model、/etc/nv_tegra_release、tegrastats、nvpmodel、nvidia-smi、または /sys/kernel/debug/nvmap が見つからない場合は、サンドボックスから Jetson ホストを認識できないことを伝え、Jetson ホスト上での実行、またはホストを認識できるサンドボックスプロファイルでの再起動をユーザーに依頼してください。
• NvMap debugfs の利用には root 権限が必要なことが多いため、権限のない実行では gpu_source: "none" が返されたり、nvmap のフィールドが不完全になったりする場合があります。
• このスキルが報告するのは観測された状態のみです。ツールが見つからない、またはアクセスできない場合に、メモリ、GPU、温度、サービス、または回収データを捏造しないでください。

エラー処理

• ヘルパーがプラットフォーム外で終了した場合、現在の環境が Jetson ホストではない、またはホストを認識できないことを報告してください。一般的な Linux の値で代用しないでください。
• tegrastats、nvpmodel、nvidia-smi、または NvMap debugfs を利用できない場合は、JSON に含まれる対応する null、false、または空のフィールドをそのまま保持し、どの指標に制限があるかを説明してください。
• snapshot.sh が不正な JSON を出力した場合は、生のエラーを報告し、ヘルパーの出力を修正してから再実行してください。合成したデバイススナップショットを手作業で編集して作成しないでください。

snapshot.sh の出力仕様

{
  "sku": "orin-nano",
  "generation": "orin",
  "product_line": "orin-nano",
  "variant": "orin-nano-8gb",
  "mem_total_gb": 8,
  "l4t_version": "36.4.0",
  "product_model": "nvidia jetson orin nano developer kit",
  "memory_kb": { "total": 8123456, "available": 4123456, "swap_total": 0, "swap_free": 0, "cached": 1234567 },
  "tegrastats_sample": "RAM 4011/8138MB (lfb 8x4MB) ...",
  "thermal_c": { "CPU": 52.3, "GPU": 49.0, "AO": 47.0 },
  "power": { "nvpmodel_id": 0, "nvpmodel_name": "MAXN" },
  "disk": [ { "mount": "/", "used_pct": 41 } ],
  "gpu_source": "nvmap:iovmm-clients",
  "gpu_devices": [],
  "gpu_processes": [],
  "nvmap": {
    "readable": true,
    "total_kb": 654321,
    "stats_total_bytes": 669985280,
    "top_clients": [ { "pid": 1234, "cmd": "vlm-server", "kb": 524288 } ]
  },
  "top_processes": [ { "pid": 4321, "cmd": "vllm", "pss_kb": 4000000 } ],
  "candidate_services": { "gdm3": { "active": "inactive", "enabled": "disabled" } }
}

gpu_source は、スキルがプロセスごとの GPU メモリを特定するために使用したデータを示すもので、呼び出し元が数値の意味を正確に把握できます。

• "nvidia-smi:compute-apps" — nvidia-smi --query-compute-apps から取得した、プロセスごとの used_memory 値です。統合された nvidia.ko スタック（現在は Thor ファミリー）で使用します。注：このスタックでは、一部の BSP で nvidia-smi のデバイスレベルの memory.used クエリが [N/A] を返します。そのため、スキルはトップレベルの合計値を読み取るのではなく、プロセスごとのリストを合算します。合計値は gpu_processes[*].used_mib に表示されます。
• "nvmap:iovmm-clients" — /sys/kernel/debug/nvmap/iovmm/clients から取得した、プロセスごとのサイズです。nvgpu スタック（現在は Orin ファミリー）で使用します。このスタックでは、nvidia-smi はスタブであり、すべてのコンピュート／メモリクエリに対して [N/A] を返します。プロセスごとのエントリーは nvmap.top_clients に、カーネル側の合計値は nvmap.total_kb および（読み取り可能な場合は）nvmap.stats_total_bytes に表示されます。
• "none" — 権威ある情報源にアクセスできません。nvgpu スタックの Jetson で権限のないユーザーとして実行した場合などが該当します（/sys/kernel/debug/nvmap 以下の debugfs には sudo が必要です）。nvmap フィールドを取得するには、sudo を付けて再実行してください。

エージェントは、重要な情報（SKU、利用可能なメモリ、gpu_source に基づく GPU の最大使用プロセス、最も高温のゾーン、電力モード）をユーザーに提示し、詳細（top_processes、gpu_processes／nvmap、services）の確認も提案してください。

安全性

このスキルは読み取り専用です。nvpmodel の変更、jetson_clocks の実行、サービスの変更は行いません。調査結果に基づいて操作する場合は、以下に引き継いでください。

• jetson-memory-audit — メモリのスナップショット取得に特化したものと、drop_caches の検証ループ
• jetson-headless-mode — GUI と補助デーモンを無効化します（安全で、元に戻せます）
• jetson-inference-mem-tune — ランタイムとメモリフラグを選択します（vLLM／SGLang／llama.cpp／TensorRT Edge-LLM）
• jetson-llm-serve — Jetson のデフォルト設定を含む vLLM および関連する GHCR イメージ
• jetson-llm-benchmark — 再現可能なレイテンシ／スループットのベンチマーク
• jetson-package — GHCR と Jetson AI Lab の PyPI インデックス、および汎用 ARM ホイール

クロスプラットフォームの動作

ファミリー	スキルが認識するバリアント	tegrastats	nvidia-smi	nvpmodel	NvMap debugfs
Jetson Thor	thor-t5000, thor-t4000	はい	はい（完全対応）	はい	はい（root）
Jetson AGX Orin	orin-agx-64gb, orin-agx-32gb, orin-agx-industrial	はい	はい（スタブ、nvgpu）*	はい	はい（root）
Jetson Orin NX	orin-nx-16gb, orin-nx-8gb	はい	はい（スタブ、nvgpu）*	はい	はい（root）
Jetson Orin Nano	orin-nano-8gb, orin-nano-4gb	はい	はい（スタブ、nvgpu）*	はい	はい（root）

* GPU がツリー内の nvgpu カーネルドライバーによって駆動される Jetson では、nvidia-smi バイナリは存在しますが、ほとんどのフィールド（Memory-Usage、電力、使用率、コンピュートプロセスの表）は Not Supported / N/A を返します。実行時にどの情報源を信頼するかを判断するため、スクリプトは機能を確認するプローブ — nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits — を実行し、このクエリが実際の整数を返した場合にのみ、プロセスごとの GPU メモリー情報に nvidia-smi を使用します。整数が返されない場合、スクリプトは /sys/kernel/debug/nvmap/iovmm/clients にフォールバックします。これは nvgpu スタックの Jetson で、プロセスごとの GPU メモリー情報の信頼できる情報源です。

スクリプトは各ツールの有無を適切に処理し、アクセスできないツールについては null / false を返します（エージェントに /sys/kernel/debug へのアクセスに必要な権限がない場合によく発生します）。バリアントの検出では、まず /proc/device-tree/model の文字列を使用して（T5000 / T4000 のような名称を認識します）、モデル文字列が汎用的な場合はメモリーサイズのヒューリスティックにフォールバックします。