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

Mit der tpu-info-Befehlszeile überwachen

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

Installation

Installieren Sie die neueste 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 alle Messwerte und Funktionen vorhanden sind. 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 Befehlszeile 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

Damit aktuelle TPU-Auslastungsdaten angezeigt werden können, ist für tpu-info eine laufende TPU-Arbeitslast mit einem unterstützten ML-Framework wie JAX oder PyTorch 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

Verwenden Sie das Flag --metric, um bestimmte Messwerte anzuzeigen. Sie können mehrere Messwerte durch Leerzeichen getrennt angeben. Einige gängige 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

Verwenden Sie das Flag --list_metrics, um alle unterstützten Messwerte anzuzeigen, 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 die Auslastungsstatistiken regelmäßig aktualisiert und angezeigt. Wenn Sie die LibTPU-Messwerte streamen möchten, fügen Sie dem Befehl tpu-info das Flag --streaming hinzu. Verwenden Sie das Flag --rate, um die Häufigkeit des Streamings in Sekunden zu steuern.

Verwenden Sie den folgenden Befehl, um die Standard-tpu-info-Messwerte 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-Einrichtung für TPUs. Er liefert detaillierte Laufzeitstatusinformationen für alle TPU-Kerne, die mit einem Host verbunden sind. Die Funktionalität wird über das Modul tpuz bereitgestellt, das Teil des Moduls libtpu.sdk im Python SDK von libtpu 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 und die Programmzähler, HLO-Standorte und Ausführungs-IDs aller Kerne zu vergleichen, um Anomalien zu identifizieren.

Verwenden Sie den folgenden Befehl, um TPU-Z-Messwerte über die Befehlszeile 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 entweder einen oder zwei Kerne pro Chip.

Feld	Beschreibung	Beispielwerte
Chip-ID	Die ID des Chips, zu dem der Kern gehört.	`0`
Global Core ID	Die eindeutige ID des Kerns im gesamten TPU-System.	`1`
Kerntyp	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       |

Sequenzer-Statusinformationen

Die Tabelle „Sequencer State Information“ (sequencer_state) enthält Informationen zum Sequenzerstatus auf einem Kern. Ein Sequenzer ist eine Steuereinheit innerhalb eines TPU-Kerns, 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 Kern gehört.	`0`
Global Core ID	Die eindeutige ID des Kerns im gesamten TPU-System.	`1`
Program Counter	Die Speicheradresse des Befehls, der vom Sequenzer ausgeführt werden soll.	`15390`
Tracemark	Die Start-ID des aktuellen oder letzten Programms. Dieses Feld ist nicht vorhanden, wenn es nicht zutreffend ist.	`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 Ausführungs-ID.	`1150`
Sequenztyp	Der Typ des Sequenzers.	`"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   |

Sequenzer-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
HLO-Details	Detaillierte Informationen zum HLO, falls verfügbar.	`[]`
ID des in die Warteschlange gestellten Programmlaufs	Die Ausführungs-ID für dieses Programm in der Warteschlange.	`81`
ID des in die Warteschlange gestellten Programmstarts	Die Start-ID für dieses in die Warteschlange gestellte Programm.	`1394130914`
Grundlegender Fehler	Enthält alle Fehlermeldungen für diesen Kern. Dieses Feld ist nicht vorhanden, wenn keine Fehler vorliegen.	`"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 für die Ausführung in die Warteschlange gestellt wurden.

Messwert	Beschreibung	Beispielwerte
Chip-ID	Die ID des Chips, zu dem der Kern 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 Start-ID des aktuellen oder letzten Programms. Dieses Feld ist nicht vorhanden, wenn es nicht zutreffend ist.	`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 Ausführungs-ID.	`1150`
Sequenztyp	Der Typ des Sequenzers.	`"\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 einige Funktionen oder Messwerte nicht sehen können, liegt das meist 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.

Mit dem Flag --version oder -v können Sie prüfen, ob die Version von tpu-info mit Ihrer Umgebung kompatibel ist:

$ 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 aktuelle Version von libtpu:

pip install --upgrade libtpu