Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

使用 tpu-info CLI 監控

tpu-info CLI 是一種工具，可偵測 Cloud TPU 裝置，並從 libtpu 程式庫讀取執行階段指標，包括記憶體用量和工作週期。這項工具支援靜態、一次性快照，以及即時串流，可持續監控指標。

安裝

使用 pip 安裝最新版本：

pip install tpu-info

或者，從來源安裝 tpu-info：

pip install git+https://github.com/google/cloud-accelerator-diagnostics/#subdirectory=tpu_info

如果您已安裝 tpu-info 版本，請確認該版本與您的環境相容，且不會遺漏任何指標和功能。詳情請參閱「缺少功能或指標」。

使用 CLI 存取標準 LibTPU 指標

使用下列指令，透過 CLI 查看預設的 tpu-info 指標：

tpu-info

輸出結果會與下列內容相似：

TPU Chips

| Chip         | Type         | Devices | PID    |
|--------------|--------------|---------|--------|
| /dev/vfio/0  | TPU v6e chip | 1       | 1022   |
| /dev/vfio/1  | TPU v6e chip | 1       | 1022   |
| /dev/vfio/2  | TPU v6e chip | 1       | 1022   |
| /dev/vfio/3  | TPU v6e chip | 1       | 1022   |

TPU Runtime Utilization

| Chip   | HBM Usage (GiB)          | Duty cycle |
|--------|--------------------------|------------|
| 8      | 17.26 GiB / 31.25 GiB    |    100.00% |
| 9      |  9.26 GiB / 31.25 GiB    |    100.00% |
| 12     |  9.26 GiB / 31.25 GiB    |    100.00% |
| 13     |  9.26 GiB / 31.25 GiB    |    100.00% |

TensorCore Utilization

| Core ID | TensorCore Utilization |
|---------|------------------------|
| 0       | 15.17%                 |
| 1       | 14.62%                 |
| 2       | 14.68%                 |
| 3       | 15.14%                 |

TPU Buffer Transfer Latency

| Buffer Size  | P50          | P90          | P95          | P999         |
|--------------|--------------|--------------|--------------|--------------|
| 8MB+         | 18264.03 us  | 33263.06 us  | 35990.98 us  | 53997.32 us  |

TPU Inbound Buffer Transfer Latency

| Buffer Size  | P50          | P90          | P95          | P999         |
|--------------|--------------|--------------|--------------|--------------|
| 8MB+         | 18316.95 us  | 32857.03 us  | 36501.59 us  | 58854.54 us  |

TPU Host Compute Latency

| Buffer Size  | P50          | P90          | P95          | P999         |
|--------------|--------------|--------------|--------------|--------------|
| 8MB+         | 678.33 us    | 2611.93 us   | 5258.30 us   | 11083.23 us  |

TPU gRPC TCP Minimum RTT

| P50      | P90      | P95      | P999     |
|----------|----------|----------|----------|
| 35.99 us | 52.15 us | 53.83 us | 55.51 us |

TPU gRPC TCP Delivery Rate

| P50           | P90           | P95           | P999          |
|---------------|---------------|---------------|---------------|
| 12305.96 Mbps | 18367.10 Mbps | 24872.11 Mbps | 44841.55 Mbps |

用量

如要查看目前的 TPU 使用率資料，tpu-info 需要執行 TPU 工作負載，並使用支援的機器學習架構，例如 JAX 或 PyTorch/XLA。您可以在終端機中執行 tpu-info 指令，並使用下列標記。

程序

使用 --process 或 -p 旗標，顯示在 TPU 上執行的程序相關資訊。

$ tpu-info --process

輸出內容應如下所示：

TPU Process Info

| Chip        | PID    | Process Name |
|-------------|--------|--------------|
| /dev/vfio/0 | 799657 | python3      |
| /dev/vfio/1 | 799657 | python3      |
| /dev/vfio/2 | 799657 | python3      |
| /dev/vfio/3 | 799657 | python3      |
| /dev/vfio/4 | 799657 | python3      |
| /dev/vfio/5 | 799657 | python3      |
| /dev/vfio/6 | 799657 | python3      |
| /dev/vfio/7 | 799657 | python3      |

指標

使用 --metric 旗標顯示特定指標。您可以指定多個指標，並以空格分隔。支援的常見指標包括：

hbm_usage
duty_cycle_percent
tensorcore_utilization
buffer_transfer_latency
host_to_device_transfer_latency
device_to_host_transfer_latency
collective_e2e_latency

$ tpu-info --metric duty_cycle_percent hbm_usage

輸出內容應如下所示：

TPU Duty Cycle

| Core ID | Duty Cycle (%) |
|---------|----------------|
| 0       | 100.00%        |
| 1       | 100.00%        |
| 2       | 100.00%        |
| 3       | 100.00%        |
| 4       | 100.00%        |
| 5       | 100.00%        |
| 6       | 100.00%        |
| 7       | 100.00%        |

TPU HBM Usage

| Chip   | HBM Usage (GiB)       |
|--------|-----------------------|
| 0      | 29.50 GiB / 31.25 GiB |
| 1      | 21.50 GiB / 31.25 GiB |
| 2      | 21.50 GiB / 31.25 GiB |
| 3      | 21.50 GiB / 31.25 GiB |
| 4      | 21.50 GiB / 31.25 GiB |
| 5      | 21.50 GiB / 31.25 GiB |
| 6      | 21.50 GiB / 31.25 GiB |
| 7      | 21.50 GiB / 31.25 GiB |

列出指標

使用 --list_metrics 旗標顯示所有支援的指標，這些指標可透過 --metric 旗標要求。

$ tpu-info --list_metrics

輸出內容應如下所示：

╭─ Supported Metrics ─────────────────────────────────────────────────────────────────────────────╮
│         grpc_tcp_min_rtt                                                                        │
│         host_to_device_transfer_latency                                                         │
│         grpc_tcp_delivery_rate                                                                  │
│         inbound_buffer_transfer_latency                                                         │
│         host_compute_latency                                                                    │
│         buffer_transfer_latency                                                                 │
│         collective_e2e_latency                                                                  │
│         device_to_host_transfer_latency                                                         │
│         hbm_usage                                                                               │
│         duty_cycle_percent                                                                      │
│         tensorcore_utilization                                                                  │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯

串流指標

串流模式會定期重新整理，並顯示最新的使用率統計資料。如要串流 LibTPU 指標，請在 tpu-info 指令中加入 --streaming 標記。使用 --rate 旗標控制串流的節奏 (以秒為單位)。

使用下列指令，透過 CLI 串流預設 tpu-info 指標：

# Refresh metrics every 2 seconds
tpu-info --streaming --rate 2

輸出結果會與下列內容相似：

Refresh rate: 0.1s
Last update: 2025-07-24 11:00:59 UTC
Libtpu version: 0.0.19.dev20250721+nightly
Accelerator type: v6e

TPU Chips

| Chip         | Type         | Devices | PID    |
|--------------|--------------|---------|--------|
| /dev/vfio/0  | TPU v6e chip | 1       | 1022   |
| /dev/vfio/1  | TPU v6e chip | 1       | 1022   |
| /dev/vfio/2  | TPU v6e chip | 1       | 1022   |
| /dev/vfio/3  | TPU v6e chip | 1       | 1022   |

TPU Runtime Utilization

| Chip   | HBM Usage (GiB)          | Duty cycle |
|--------|--------------------------|------------|
| 8      | 17.26 GiB / 31.25 GiB    |    100.00% |
| 9      |  9.26 GiB / 31.25 GiB    |    100.00% |
| 12     |  9.26 GiB / 31.25 GiB    |    100.00% |
| 13     |  9.26 GiB / 31.25 GiB    |    100.00% |

TensorCore Utilization

| Core ID | TensorCore Utilization |
|---------|------------------------|
| 0       | 15.17%                 |
| 1       | 14.62%                 |
| 2       | 14.68%                 |
| 3       | 15.14%                 |

TPU Buffer Transfer Latency

| Buffer Size  | P50          | P90          | P95          | P999         |
|--------------|--------------|--------------|--------------|--------------|
| 8MB+         | 18264.03 us  | 33263.06 us  | 35990.98 us  | 53997.32 us  |

TPU Inbound Buffer Transfer Latency

| Buffer Size  | P50          | P90          | P95          | P999         |
|--------------|--------------|--------------|--------------|--------------|
| 8MB+         | 18316.95 us  | 32857.03 us  | 36501.59 us  | 58854.54 us  |

TPU Host Compute Latency

| Buffer Size  | P50          | P90          | P95          | P999         |
|--------------|--------------|--------------|--------------|--------------|
| 8MB+         | 678.33 us    | 2611.93 us   | 5258.30 us   | 11083.23 us  |

TPU gRPC TCP Minimum RTT

| P50      | P90      | P95      | P999     |
|----------|----------|----------|----------|
| 35.99 us | 52.15 us | 53.83 us | 55.51 us |

TPU gRPC TCP Delivery Rate

| P50           | P90           | P95           | P999          |
|---------------|---------------|---------------|---------------|
| 12305.96 Mbps | 18367.10 Mbps | 24872.11 Mbps | 44841.55 Mbps |

TPU-Z 指標

TPU-Z 是 TPU 的遙測和偵錯設施，可提供連結至主機的所有 TPU 核心詳細執行階段狀態資訊。這項功能透過 tpuz 模組提供，該模組是 libtpu Python SDK 中 libtpu.sdk 模組的一部分。這個模組會提供每個核心狀態的快照。

TPU-Z 的主要用途是診斷分散式 TPU 工作負載中的停止或死結。您可以在主機上查詢 TPU-Z 服務，擷取每個核心的狀態，比較所有核心的程式計數器、HLO 位置和執行 ID，找出異常狀況。

使用下列指令，透過 CLI 查看 TPU-Z 指標：

tpu-info --metric core_state
tpu-info --metric sequencer_state
tpu-info --metric sequencer_state_detailed
tpu-info --metric queued_program

輸出內容應包含 core_state、sequencer_state、sequencer_state_detailed 和 queued_programs 資料表。

核心州別資訊

「核心狀態資訊」(core_state) 表格提供特定晶片核心的相關資訊。視世代而定，TPU 每個晶片有一個或兩個核心。

欄位	說明	範例值
晶片 ID	核心所屬晶片的 ID。	`0`
全球核心 ID	整個 TPU 系統中核心的專屬 ID。	`1`
核心類型	TPU 核心類型。	`"TPU_CORE_TYPE_TENSOR_CORE"` `"TPU_CORE_TYPE_SPARSE_CORE"`
xdb 伺服器正在執行	指出 Accelerator Debugger (XDB) 伺服器是否在特定 TPU 核心上執行。	`True`

輸出內容應類似下表：

Core Information

| Chip ID | Global Core ID | Core Type                   | xdb Server |
|---------|----------------|-----------------------------|------------|
| 0       | 0              | TPU_CORE_TYPE_TENSOR_CORE   | True       |
| 0       | 1              | TPU_CORE_TYPE_SPARSE_CORE   | True       |
| 1       | 2              | TPU_CORE_TYPE_SPARSE_CORE   | False      |
| 1       | 3              | TPU_CORE_TYPE_SPARSE_CORE   | False      |
| 2       | 4              | TPU_CORE_TYPE_SPARSE_CORE   | True       |
| 2       | 5              | TPU_CORE_TYPE_SPARSE_CORE   | True       |

定序器狀態資訊

「定序器狀態資訊」(sequencer_state) 表格提供核心上定序器狀態的相關資訊。定序器是 TPU 核心內的控制單元，負責擷取、解碼及自動化調度指令執行作業。單一核心可以有多個定序器。

指標	說明	範例值
晶片 ID	核心所屬晶片的 ID。	`0`
全球核心 ID	整個 TPU 系統中核心的專屬 ID。	`1`
程式計數器	定序器要執行的指令記憶體位址。	`15390`
Tracemark	目前或最近一次執行的程式啟動 ID。如不適用，這個欄位會顯示空白。	`2147483647`
課程 ID	與特定程式例項相關聯的 ID，該例項會啟動，以便在 TPU 核心上執行。	`3230481660274331500`
執行作業 ID	與程式相關聯的執行 ID。	`1150`
序列類型	定序器類型。	`"TPU_SEQUENCER_TYPE_SPARSE_CORE_SEQUENCER"` `"TPU_SEQUENCER_TYPE_SPARSE_CORE_TILE_EXECUTE_CORE_SEQUENCER"`

輸出內容應類似下表：

Sequencer Info

| Chip ID | Global Core | Program Counter:Tag | Tracemark  | Program ID | Run ID | Sequence Type                 |
|---------|-------------|---------------------|------------|------------|--------|-------------------------------|
| 0       | 0           | 760:1               | 2147483647 | -5.75e17   | 1150   | TPU_SEQ_SPARSE_CORE_SEQUENCER |
| 0       | 1           | 9:0                 | 0          | -1         | -1     | TPU_SEQ_SPARSE_TILE_EXECUTE   |
| 0       | 1           | 0:0                 | 0          | -1         | -1     | TPU_SEQ_SPARSE_TILE_EXECUTE   |
| 1       | 2           | 9:0                 | 0          | -1         | -1     | TPU_SEQ_SPARSE_TILE_EXECUTE   |
| 1       | 3           | 0:0                 | 0          | -1         | -1     | TPU_SEQ_SPARSE_TILE_EXECUTE   |
| 1       | 3           | 9:0                 | 0          | -1         | -1     | TPU_SEQ_SPARSE_TILE_EXECUTE   |
| 1       | 3           | 0:0                 | 0          | -1         | -1     | TPU_SEQ_SPARSE_TILE_EXECUTE   |
| 2       | 4           | 9:0                 | 0          | -1         | -1     | TPU_SEQ_SPARSE_TILE_EXECUTE   |
| 2       | 4           | 0:0                 | 0          | -1         | -1     | TPU_SEQ_SPARSE_TILE_EXECUTE   |
| 2       | 4           | 9:0                 | 0          | -1         | -1     | TPU_SEQ_SPARSE_TILE_EXECUTE   |
| 2       | 5           | 9:0                 | 0          | -1         | -1     | TPU_SEQ_SPARSE_TILE_EXECUTE   |
| 2       | 5           | 0:0                 | 0          | -1         | -1     | TPU_SEQ_SPARSE_TILE_EXECUTE   |

定序器狀態資訊 (詳細)

「Sequencer State Information (detailed)」(序號產生器狀態資訊 (詳細)) (sequencer_state_detailed) 表格提供「Sequencer State Information」(序號產生器狀態資訊) (sequencer_state) 表格中的所有資訊，以及下列額外指標：

指標	說明	範例值
HLO 詳細資料	詳細的 HLO 資訊 (如有)。	`[]`
已加入佇列的程式執行 ID	這個已加入佇列的程式的執行 ID。	`81`
已加入佇列的計畫啟動 ID	這個已加入佇列的節目啟動 ID。	`1394130914`
核心錯誤	包含這個核心的任何錯誤訊息。如果沒有錯誤，這個欄位就不會顯示。	`"Failed to parse launch id: 0xdcf36153"`
HLO 位置	高階最佳化工具 (HLO) 位置資訊。	`"no HLO mapping"` `"HLO: fusion.11; HLO computation: main.126_spmd"`

輸出內容應類似下表：

Sequencer States (Detailed)

| Chip ID | Global Core ID | Program Counter | Tracemark  | Program ID           | Run ID | Sequence Type                            | Core Error                                               | HLO Location   | HLO Details |
|---------|----------------|-----------------|------------|----------------------|--------|------------------------------------------|----------------------------------------------------------|----------------|-------------|
| 0       | 0              | 760             | 2147483647 | -5752110712385440928 | 114    | TPU_SEQUENCER_TYPE_TENSOR_CORE_SEQUENCER | Failed to parse launch id: 0xdcf36109                    | no HLO mapping | []          |
| 0       | 1              | 9               | 0          | -1                   | -1     | TPU_SEQUENCER_TYPE_SPARSE_CORE_SEQUENCER | Compiler metadata or executable fingerprint not found.   | None           | None        |
| 0       | 1              | 0               | 0          | -1                   | -1     | TPU_SEQUENCER_TYPE_SPARSE_CORE_TILE_EXE… | Compiler metadata or executable fingerprint not found.   | None           | None        |
| 0       | 1              | 0               | 0          | -1                   | -1     | TPU_SEQUENCER_TYPE_SPARSE_CORE_TILE_EXE… | Compiler metadata or executable fingerprint not found.   | None           | None        |
| ...     | ...            | ...             | ...        | ...                  | ...    | ...                                      | ...                                                      | ...            | ...         |

待播節目

「已加入佇列的程式」(queued_programs) 表格會列出已加入執行佇列的程式。

指標	說明	範例值
晶片 ID	核心所屬晶片的 ID。	`0`
全球核心	整個 TPU 系統中核心的專屬 ID。	`1`
程式計數器：標記	定序器要執行的指令記憶體位址。	`15390`
Tracemark	目前或最近一次執行的程式啟動 ID。如不適用，這個欄位會顯示空白。	`2147483647`
課程 ID	與特定程式例項相關聯的 ID，該例項會啟動，以便在 TPU 核心上執行。	`3230481660274331500`
執行作業 ID	與程式相關聯的執行 ID。	`1150`
序列類型	定序器類型。	`"\ufffdU\ufffd4j\u7c6e\ufffd\ufffd{\u0017\ufffd\ufffdHHV\ufffdD\ufffde\uff"`

Queued Programs

| Chip ID | Global Core | Program Counter:Tag | Tracemark | Program ID  | Run ID | Sequence Type                      |
|---------|-------------|---------------------|-----------|-------------|--------|------------------------------------|
| 0       | 0           | 10712385440928      | 1220      | -5.75e17    | 1220   | \ufffdU\\...ufffd{\\u0017\\...\\   |
| 0       | 1           | 31435440272417      | 1530      | -1          | 1530   | \ufff4j\\...\\ufffd{\\u0017\\...\\ |
| 0       | 1           | 10230672051156      | 1410      | -1          | 1410   | \ufffde\\...\\ufffd{\\u0017\\...\\ |
| ...     | ...         | ...                 | ...       | ...         | ...    | ...                                |

缺少功能或指標

如果無法查看部分功能或指標，最常見的原因是 libtpu 版本過舊。tpu-info 中的功能和指標會納入 libtpu 版本，舊版可能缺少新功能和指標。

如要確認 tpu-info 版本與環境相容，請使用 --version 或 -v 標記：

$ tpu-info --version

以下輸出內容顯示相容環境的範例：

-   tpu-info version: 0.5.1
-   libtpu version: 0.0.18
-   accelerator type: v6e

以下輸出內容顯示不相容的環境範例：

-   tpu-info version: 0.5.1
-   libtpu version: N/A (incompatible environment)
-   accelerator type: N/A (incompatible environment)

如果使用的是舊版，請更新至最新版 libtpu：

pip install --upgrade libtpu