Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Mit der tpu-info-CLI überwachen

Die tpu-info CLI ist ein Tool zum Erkennen von Cloud TPU-Geräten und zum Lesen von Laufzeitmesswerten aus der libtpu-Bibliothek, einschließlich Arbeitsspeichernutzung und Duty Cycle. Es unterstützt statische, einmalige Momentaufnahmen und Livestreaming, um Messwerte kontinuierlich zu überwachen.

Installation

Installieren Sie die aktuelle Version mit pip:

pip install tpu-info

Alternativ können Sie tpu-info aus der Quelle installieren:

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

Wenn Sie bereits eine Version von tpu-info installiert haben, prüfen Sie, ob sie mit Ihrer Umgebung kompatibel ist und ob Messwerte und Funktionen fehlen. Weitere Informationen finden Sie unter Fehlende Funktionen oder Messwerte.

Über die Befehlszeile auf Standard-LibTPU-Messwerte zugreifen

Verwenden Sie den folgenden Befehl, um die Standardmesswerte für tpu-info mit der CLI aufzurufen:

tpu-info

Die Ausgabe sieht etwa so aus:

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 |

Nutzung

Um aktuelle Daten zur TPU-Auslastung aufzurufen, ist für tpu-info eine laufende TPU-Arbeitslast mit einem unterstützten ML-Framework wie JAX oder PyTorch/XLA erforderlich. Sie können den Befehl tpu-info in Ihrem Terminal mit den folgenden Flags ausführen.

Prozess

Verwenden Sie das Flag --process oder -p, um Informationen zu den Prozessen aufzurufen, die auf der TPU ausgeführt werden.

$ tpu-info --process

Die Ausgabe sollte in etwa so aussehen:

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      |

Messwert

Mit dem Flag --metric können Sie bestimmte Messwerte anzeigen. Sie können mehrere durch Leerzeichen getrennte Messwerte angeben. Einige häufig unterstützte Messwerte sind:

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

Die Ausgabe sollte in etwa so aussehen:

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 |

Messwerte auflisten

Mit dem Flag --list_metrics können Sie alle unterstützten Messwerte anzeigen, die mit dem Flag --metric angefordert werden können.

$ tpu-info --list_metrics

Die Ausgabe sollte in etwa so aussehen:

╭─ 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                                                                  │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯

Stream-Messwerte

Im Streamingmodus werden regelmäßig aktuelle Statistiken zur Nutzung aktualisiert und angezeigt. Wenn Sie die LibTPU-Messwerte streamen möchten, fügen Sie dem Befehl tpu-info das Flag --streaming hinzu. Mit dem Flag --rate können Sie die Häufigkeit des Streamings in Sekunden festlegen.

Verwenden Sie den folgenden Befehl, um die Standardmesswerte von tpu-info mit der Befehlszeile zu streamen:

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

Die Ausgabe sieht etwa so aus:

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-Messwerte

TPU-Z ist eine Telemetrie- und Debugging-Funktion für TPUs. Sie enthält detaillierte Laufzeitstatusinformationen für alle TPU-Cores, die an einen Host angehängt sind. Die Funktionalität wird über das Modul tpuz bereitgestellt, das Teil des Moduls libtpu.sdk im libtpu Python SDK ist. Das Modul bietet einen Snapshot des Status jedes Kerns.

Der primäre Anwendungsfall für TPU-Z ist die Diagnose von Hängern oder Deadlocks in verteilten TPU-Arbeitslasten. Sie können den TPU-Z-Dienst auf Hosts abfragen, um den Status jedes Kerns zu erfassen. Dabei werden die Programmzähler, HLO-Speicherorte und Ausführungs-IDs aller Kerne verglichen, um Anomalien zu erkennen.

Verwenden Sie den folgenden Befehl, um TPU-Z-Messwerte über die CLI aufzurufen:

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

Die Ausgabe sollte die Tabellen core_state, sequencer_state, sequencer_state_detailed und queued_programs enthalten.

Wichtige Statusinformationen

Die Tabelle „Core State Information“ (core_state) enthält Informationen zu den Kernen eines bestimmten Chips. TPUs haben je nach Generation einen oder zwei Kerne pro Chip.

Feld	Beschreibung	Beispielwerte
Chip-ID	Die ID des Chips, zu dem der Core gehört.	`0`
Globale Core-ID	Die eindeutige ID des Kerns im gesamten TPU-System.	`1`
Core-Typ	Der Typ des TPU-Kerns.	`"TPU_CORE_TYPE_TENSOR_CORE"` `"TPU_CORE_TYPE_SPARSE_CORE"`
xdb-Server wird ausgeführt	Gibt an, ob der Accelerator Debugger-Server (XDB) auf einem bestimmten TPU-Kern ausgeführt wird.	`True`

Die Ausgabe sollte in etwa so aussehen:

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       |

Informationen zum Sequenzerstatus

Die Tabelle „Sequencer State Information“ (sequencer_state) enthält Informationen zu einem Sequencer-Status auf einem Core. Ein Sequencer ist eine Steuereinheit in einem TPU-Kern, die für das Abrufen, Decodieren und Orchestrieren der Ausführung von Anweisungen verantwortlich ist. Für einen einzelnen Kern kann es mehrere Sequenzer geben.

Messwert	Beschreibung	Beispielwerte
Chip-ID	Die ID des Chips, zu dem der Core gehört.	`0`
Globale Core-ID	Die eindeutige ID des Kerns im gesamten TPU-System.	`1`
Programmzähler	Die Speicheradresse des Befehls, der vom Sequenzer ausgeführt werden soll.	`15390`
Tracemark	Die Launch-ID des aktuellen oder letzten Programms. Dieses Feld ist nicht vorhanden, falls nicht zutreffend.	`2147483647`
Programm-ID	Die ID, die einer bestimmten Instanz eines Programms zugeordnet ist, das zur Ausführung auf einem TPU-Kern gestartet wird.	`3230481660274331500`
Ausführungs-ID	Die mit dem Programm verknüpfte Lauf-ID.	`1150`
Sequenztyp	Der Typ des Sequenzierers.	`"TPU_SEQUENCER_TYPE_SPARSE_CORE_SEQUENCER"` `"TPU_SEQUENCER_TYPE_SPARSE_CORE_TILE_EXECUTE_CORE_SEQUENCER"`

Die Ausgabe sollte in etwa so aussehen:

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-Statusinformationen (detailliert)

Die Tabelle „Sequencer State Information (detailed)“ (sequencer_state_detailed) enthält alle Informationen aus der Tabelle „Sequencer State Information“ (sequencer_state) sowie die folgenden zusätzlichen Messwerte:

Messwert	Beschreibung	Beispielwerte
Details zu HLOs	Detaillierte Informationen zu HLO, falls verfügbar.	`[]`
ID des Programmlaufs in der Warteschlange	Die Lauf-ID für dieses in die Warteschlange gestellte Programm.	`81`
ID für den geplanten Programmstart	Die Launch-ID für dieses Programm in der Warteschlange.	`1394130914`
Grundlegender Fehler	Enthält alle Fehlermeldungen für diesen Core. Dieses Feld ist nicht vorhanden, wenn keine Fehler auftreten.	`"Failed to parse launch id: 0xdcf36153"`
HLO-Standort	Standortinformationen für High Level Optimizer (HLO).	`"no HLO mapping"` `"HLO: fusion.11; HLO computation: main.126_spmd"`

Die Ausgabe sollte in etwa so aussehen:

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        |
| ...     | ...            | ...             | ...        | ...                  | ...    | ...                                      | ...                                                      | ...            | ...         |

Programme in der Warteschlange

Die Tabelle „In die Warteschlange gestellte Programme“ (queued_programs) enthält die Liste der Programme, die zur Ausführung in die Warteschlange gestellt wurden.

Messwert	Beschreibung	Beispielwerte
Chip-ID	Die ID des Chips, zu dem der Core gehört.	`0`
Global Core	Die eindeutige ID des Kerns im gesamten TPU-System.	`1`
Program Counter:Tag	Die Speicheradresse des Befehls, der vom Sequenzer ausgeführt werden soll.	`15390`
Tracemark	Die Launch-ID des aktuellen oder letzten Programms. Dieses Feld ist nicht vorhanden, falls nicht zutreffend.	`2147483647`
Programm-ID	Die ID, die einer bestimmten Instanz eines Programms zugeordnet ist, das zur Ausführung auf einem TPU-Kern gestartet wird.	`3230481660274331500`
Ausführungs-ID	Die mit dem Programm verknüpfte Lauf-ID.	`1150`
Sequenztyp	Der Typ des Sequenzierers.	`"\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\\...\\ |
| ...     | ...         | ...                 | ...       | ...         | ...    | ...                                |

Fehlende Funktionen oder Messwerte

Wenn Sie bestimmte Funktionen oder Messwerte nicht sehen können, liegt das meistens an einer veralteten libtpu-Version. Die Funktionen und Messwerte in tpu-info sind in den libtpu-Releases enthalten. In veralteten Versionen fehlen möglicherweise neue Funktionen und Messwerte.

Wenn Sie prüfen möchten, ob die Version von tpu-info mit Ihrer Umgebung kompatibel ist, verwenden Sie das Flag --version oder -v:

$ tpu-info --version

Die folgende Ausgabe zeigt ein Beispiel für eine kompatible Umgebung:

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

Die folgende Ausgabe zeigt ein Beispiel für eine inkompatible Umgebung:

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

Wenn Sie eine veraltete Version verwenden, aktualisieren Sie auf die neueste Version von libtpu:

pip install --upgrade libtpu