jetson-diagnostic

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Jetson Diagnostic

Jetson 诊断

A unified, agent-friendly view of a running Jetson device. Replaces the need to remember which of

tegrastats

jtop

procrank

/sys/kernel/debug/nvmap

nvpmodel

free

swapon

df

, and

systemctl list-units

produces which slice of the truth.

为运行中的Jetson设备提供统一、便于Agent使用的视图。无需再记忆

tegrastats

、

jtop

、

procrank

、

/sys/kernel/debug/nvmap

、

nvpmodel

、

free

、

swapon

、

df

以及

systemctl list-units

这些命令分别能获取哪些系统信息。

Purpose

用途

Capture a read-only health snapshot from the Jetson host so agents can answer device identity, memory, GPU, thermal, power, storage, and service-state questions using live data instead of guesses.

从Jetson主机捕获只读的健康快照，让Agent可以使用实时数据回答关于设备标识、内存、GPU、散热、电源、存储以及服务状态的问题，而非仅凭猜测。

When to use

使用场景

Activate when the user asks:

"What is this Jetson? What SKU? How much memory?"
"What's running on this Jetson right now?"
"Why is my Jetson slow / hot / out of memory?"
"Give me a snapshot of GPU / CPU / power usage."
"What does my tegrastats output mean?"
"Which services are running that I could turn off?"

The user has installed

jetson-memory-audit

jetson-headless-mode

jetson-inference-mem-tune

jetson-llm-benchmark

jetson-llm-serve

, or

jetson-package

and needs a baseline measurement before running them.

Do not use this skill to change power modes, drop caches, stop services, install packages, serve models, or tune inference flags. Report the observed state, then hand off to the action-oriented skill.

当用户提出以下问题时激活此技能：

"这是哪款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

，需要在运行前获取基准测量数据。

请勿使用此技能修改电源模式、释放缓存、停止服务、安装包、部署模型或调整推理参数。仅报告观测到的状态，然后转交至面向操作的技能。

Prerequisites

前置条件

Run on the Jetson host, or in a sandbox/container with host-visible Jetson system paths and process data.

在Jetson主机上运行，或在可访问主机Jetson系统路径和进程数据的沙箱/容器中运行。

Available Scripts

可用脚本

Script	Purpose	Arguments
`scripts/snapshot.sh`	Emits the all-in-one JSON snapshot for identity, memory, GPU, thermal, power, disk, top processes, and candidate services.	`--human` , `--tegra-secs N` , `--top-procs N` .
`scripts/mem_summary.sh`	Emits a compact human-readable RAM/GPU/swap summary.	`--short` , `--watch` , `--interval N` .
`scripts/detect_jetson.sh`	Exports or prints canonical Jetson SKU/generation/product-line fields for this repo.	No arguments.

If your agent runtime supports

run_script

, use it to run

scripts/snapshot.sh

scripts/mem_summary.sh

and summarize the returned output. Otherwise run the scripts with

bash

from the repository root.

脚本	用途	参数
`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/世代/产品线字段。	无参数

如果你的Agent运行时支持

run_script

，请使用它来运行

scripts/snapshot.sh

或

scripts/mem_summary.sh

并总结返回的输出。否则，请从仓库根目录使用

bash

运行这些脚本。

Instructions

操作步骤

Run
```
scripts/snapshot.sh
```
for the all-in-one JSON view (preferred default).
For a quick human-readable memory line, run
```
scripts/mem_summary.sh
```
.
To explain a single tegrastats line the user has pasted, see
```
references/tegrastats-fields.md
```
.
To explain the NvMap clients output, see
```
references/nvmap-clients.md
```
.

运行
```
scripts/snapshot.sh
```
获取一体化JSON视图（推荐默认选项）。
如需快速查看人类可读的内存信息，运行
```
scripts/mem_summary.sh
```
。
如需解释用户粘贴的单条tegrastats输出，请查看
```
references/tegrastats-fields.md
```
。
如需解释NvMap客户端输出，请查看
```
references/nvmap-clients.md
```
。

Reporting guidance

报告指南

Run the matching helper script before summarizing device state, and report only fields returned by that script. If direct execution is blocked by the runtime, run it with

bash {baseDir}/scripts/<script-name>

rather than trying to chmod files.

For "what is this Jetson" questions, quote
```
product_model
```
or
```
sku
```
,
```
variant
```
,
```
l4t_version
```
, and
```
mem_total_gb
```
.
For "slow and hot" questions, run
```
snapshot.sh
```
and summarize both sides of the symptom:
```
thermal_c
```
for heat, plus
```
top_processes
```
,
```
gpu_processes
```
,
```
nvmap.top_clients
```
, or
```
gpu_source
```
for load. End with a concrete handoff such as
```
jetson-memory-audit
```
,
```
jetson-headless-mode
```
, or
```
jetson-inference-mem-tune
```
.
For "which process is using memory" questions, run
```
snapshot.sh
```
and name the leading process as
```
pid <number>
```
,
```
cmd
```
, and its
```
pss_kb
```
/ MiB value. If NvMap GPU memory is the relevant signal, also quote
```
gpu_source
```
and the top
```
nvmap.top_clients
```
or
```
gpu_processes
```
entry.

If your agent runtime does not automatically execute helper scripts relative to this skill directory, resolve script paths with the AgentSkills

{baseDir}

placeholder:

bash

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

Do not call

jetson-diagnostic

as a tool name unless the runtime explicitly registers skills as callable tools; Agent Skills are normally instructions plus files, not direct tool functions.

All scripts source the canonical platform detector at

skills/jetson-diagnostic/scripts/detect_jetson.sh

(exports

JETSON_SKU

JETSON_GENERATION

JETSON_PRODUCT_LINE

JETSON_VARIANT

JETSON_MEM_GB

JETSON_L4T_VERSION

JETSON_PRODUCT_MODEL

). Other skills may source this detector rather than duplicating Jetson identification logic. Exits 2 with a remediation message off-platform.

在总结设备状态前运行匹配的辅助脚本，仅报告该脚本返回的字段。如果运行时阻止直接执行，请使用

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 <编号>
```
、
```
cmd
```
及其
```
pss_kb
```
/MiB值。如果NvMap GPU内存是相关指标，还需引用
```
gpu_source
```
以及顶级
```
nvmap.top_clients
```
或
```
gpu_processes
```
条目。

如果你的Agent运行时无法自动相对于此技能目录执行辅助脚本，请使用AgentSkills的

{baseDir}

占位符解析脚本路径：

bash

{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识别逻辑。在非Jetson平台上运行时会以状态码2退出并返回修复提示信息。

Limitations

限制

Seeing this skill file does not guarantee access to Jetson host hardware. If
```
/proc/device-tree/model
```
,
```
/etc/nv_tegra_release
```
,
```
tegrastats
```
,
```
nvpmodel
```
,
```
nvidia-smi
```
, or
```
/sys/kernel/debug/nvmap
```
are missing inside a NemoClaw/OpenClaw sandbox, say the sandbox lacks Jetson host visibility and ask the user to run on the Jetson host or relaunch with a host-visible sandbox profile.
NvMap debugfs often requires root, so unprivileged runs may report
```
gpu_source: "none"
```
or incomplete
```
nvmap
```
fields.
This skill reports observed state only. Do not fabricate memory, GPU, thermal, service, or reclamation data when a tool is missing or inaccessible.

拥有此技能文件并不保证能访问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、散热、服务或回收数据。

Error handling

错误处理

If a helper exits off-platform, report that the current environment is not a Jetson host or lacks host visibility; do not substitute generic Linux values.
If
```
tegrastats
```
,
```
nvpmodel
```
,
```
nvidia-smi
```
, or NvMap debugfs are unavailable, preserve the corresponding
```
null
```
,
```
false
```
, or empty fields from the JSON and explain which signal is limited.
If
```
snapshot.sh
```
emits malformed JSON, report the raw failure and rerun after fixing the helper output; do not hand-edit a synthetic device snapshot.

如果辅助脚本在非Jetson平台退出，请报告当前环境不是Jetson主机或无法访问主机；请勿替换为通用Linux值。
如果
```
tegrastats
```
、
```
nvpmodel
```
、
```
nvidia-smi
```
或NvMap debugfs不可用，请保留JSON中对应的
```
null
```
、
```
false
```
或空字段，并说明哪些指标受限。
如果
```
snapshot.sh
```
输出格式错误的JSON，请报告原始失败信息，修复辅助脚本输出后重新运行；请勿手动编辑合成设备快照。

Output contract for

snapshot.sh

snapshot.sh

输出约定

json

{
  "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

names the specific datum the skill used to attribute per-process GPU memory, so the caller can tell exactly what the numbers represent:

```
"nvidia-smi:compute-apps"
```
— per-process
```
used_memory
```
values from
```
nvidia-smi --query-compute-apps
```
. Used on the unified
```
nvidia.ko
```
stack (Thor family today). Note: on this stack
```
nvidia-smi
```
's device-level
```
memory.used
```
query returns
```
[N/A]
```
on some BSPs, which is why the skill sums the per-process list rather than reading a top-level total. The summed total appears in
```
gpu_processes[*].used_mib
```
.
```
"nvmap:iovmm-clients"
```
— per-process sizes from
```
/sys/kernel/debug/nvmap/iovmm/clients
```
. Used on the
```
nvgpu
```
stack (Orin family today), where
```
nvidia-smi
```
is a stub that returns
```
[N/A]
```
for every compute/memory query. Per-process entries appear in
```
nvmap.top_clients
```
; the kernel-side total is in
```
nvmap.total_kb
```
and (when readable)
```
nvmap.stats_total_bytes
```
.
```
"none"
```
— no authoritative source reachable. Typical when running unprivileged on an
```
nvgpu
```
-stack Jetson (debugfs under
```
/sys/kernel/debug/nvmap
```
needs
```
sudo
```
); rerun with
```
sudo
```
to populate the
```
nvmap
```
fields.

The agent should present the salient parts back to the user (SKU, available memory, top GPU consumer per

gpu_source

, hottest zone, power mode) and offer to drill into specifics (

top_processes

gpu_processes

nvmap

services

json

{
  "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系列）。注意：在此驱动栈上，
```
nvidia-smi
```
的设备级
```
memory.used
```
查询在部分BSP中会返回
```
[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
```
权限）；请使用
```
sudo
```
重新运行以填充
```
nvmap
```
字段。

Agent应向用户展示关键信息（SKU、可用内存、

gpu_source

对应的顶级GPU占用进程、最热区域、电源模式），并提供深入查看详情的选项（

top_processes

、

gpu_processes

nvmap

、

services

）。

Safety

安全性

This skill is read-only. It does not change

nvpmodel

, does not run

jetson_clocks

, does not modify services. To act on findings, hand off to:

```
jetson-memory-audit
```
— focused memory snapshot + drop_caches verify loop
```
jetson-headless-mode
```
— disable GUI + auxiliary daemons (safe, reversible)
```
jetson-inference-mem-tune
```
— pick runtime + memory flags (vLLM / SGLang / llama.cpp / TensorRT Edge-LLM)
```
jetson-llm-serve
```
— vLLM and related GHCR images with Jetson defaults
```
jetson-llm-benchmark
```
— reproducible latency / throughput benchmarks
```
jetson-package
```
— GHCR + Jetson AI Lab PyPI indexes vs generic ARM wheels

此技能为只读。它不会修改

nvpmodel

设置，不会运行

jetson_clocks

，也不会修改服务配置。如需根据诊断结果执行操作，请转交至以下技能：

```
jetson-memory-audit
```
— 聚焦内存快照+释放缓存验证循环
```
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索引 vs 通用ARM轮子包

Cross-platform behavior

跨平台行为

Family	Variants the skill recognises	`tegrastats`	`nvidia-smi`	`nvpmodel`	NvMap debugfs
Jetson Thor	`thor-t5000` , `thor-t4000`	yes	yes (full)	yes	yes (root)
Jetson AGX Orin	`orin-agx-64gb` , `orin-agx-32gb` , `orin-agx-industrial`	yes	yes (stub, `nvgpu` )*	yes	yes (root)
Jetson Orin NX	`orin-nx-16gb` , `orin-nx-8gb`	yes	yes (stub, `nvgpu` )*	yes	yes (root)
Jetson Orin Nano	`orin-nano-8gb` , `orin-nano-4gb`	yes	yes (stub, `nvgpu` )*	yes	yes (root)

* On Jetsons whose GPU is driven by the in-tree

nvgpu

kernel driver, the

nvidia-smi

binary is present but most fields (

Memory-Usage

, power, utilisation, compute-process table) report

Not Supported

N/A

. To decide which source to trust at runtime, the script does a capability probe —

nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits

— and only uses

nvidia-smi

for per-process GPU memory when that query returns a real integer. When it doesn't, the script falls back to

/sys/kernel/debug/nvmap/iovmm/clients

, which on

nvgpu

-stack Jetsons is the authoritative per-process GPU-memory source.

The script handles each tool's presence gracefully and reports

null

false

for tools it cannot reach (typical when the agent isn't running with the privilege needed for

/sys/kernel/debug

). Variant detection uses the

/proc/device-tree/model

string first (recognising names like

T5000

T4000

) and falls back to memory-size heuristics when the model string is generic.

系列	技能可识别的变体	`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）

* 在由内核态

nvgpu

驱动GPU的Jetson设备上，

nvidia-smi

二进制文件存在，但大多数字段（

Memory-Usage

、电源、利用率、计算进程表）会报告

Not Supported

N/A

。为了在运行时确定信任哪个数据源，脚本会进行能力探测——

nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits

——只有当该查询返回真实整数时，才会使用

nvidia-smi

统计进程级GPU内存。否则，脚本会回退到

/sys/kernel/debug/nvmap/iovmm/clients

，这是

nvgpu

驱动栈Jetson设备上权威的进程级GPU内存数据源。

脚本会优雅地处理各工具的存在状态，对无法访问的工具报告

null

false

（通常在Agent没有足够权限访问

/sys/kernel/debug

时出现）。变体检测优先使用

/proc/device-tree/model

字符串（识别

T5000

T4000

等名称），当模型字符串通用时回退到内存大小启发式检测。

jetson-diagnostic

Original

Translation

Jetson Diagnostic

Jetson 诊断

Purpose

用途

When to use

使用场景

Prerequisites

前置条件

Available Scripts

可用脚本

Instructions

操作步骤

Reporting guidance

报告指南

Limitations

限制

Error handling

错误处理

Output contract for
`snapshot.sh`

`snapshot.sh`
输出约定

Safety

安全性

Cross-platform behavior

跨平台行为

jetson-diagnostic

Original

Translation

Jetson Diagnostic

Jetson 诊断

Purpose

用途

When to use

使用场景

Prerequisites

前置条件

Available Scripts

可用脚本

Instructions

操作步骤

Reporting guidance

报告指南

Limitations

限制

Error handling

错误处理

Output contract for snapshot.sh

snapshot.sh输出约定

Safety

安全性

Cross-platform behavior

跨平台行为

Output contract for
`snapshot.sh`

`snapshot.sh`
输出约定