Monitoraggio con l'interfaccia a riga di comando tpu-info
La CLI tpu-info è uno strumento per rilevare i dispositivi Cloud TPU e leggere le metriche di runtime dalla libreria libtpu, tra cui la memoria utilizzata e il ciclo di lavoro. Supporta snapshot statici una tantum e lo streaming in diretta per monitorare le metriche in modo continuo.
Installazione
Installa l'ultima release utilizzando pip:
pip install tpu-info
In alternativa, installa tpu-info dal codice sorgente:
pip install git+https://github.com/google/cloud-accelerator-diagnostics/#subdirectory=tpu_info
Se hai già installato una versione di tpu-info, assicurati che sia compatibile con il tuo ambiente e che non manchino metriche e funzionalità.
Per saperne di più, consulta Funzionalità o metriche mancanti.
Accedi alle metriche LibTPU standard utilizzando l'interfaccia a riga di comando
Utilizza il seguente comando per visualizzare le metriche tpu-info predefinite con l'interfaccia a riga di comando:
tpu-info
L'output è simile al seguente:
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 |
Utilizzo
Per visualizzare i dati di utilizzo attuali della TPU, tpu-info richiede un workload TPU in esecuzione con un framework ML supportato, come JAX o PyTorch. Puoi eseguire il comando tpu-info nel terminale con i seguenti flag.
Processo
Utilizza il flag --process o -p per visualizzare le informazioni sui processi
in esecuzione sulla TPU.
$ tpu-info --process
L'output dovrebbe essere simile al seguente:
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 |
Metrica
Utilizza il flag --metric per visualizzare metriche specifiche. Puoi specificare più metriche separate da spazi. Alcune metriche comuni supportate sono:
hbm_usageduty_cycle_percenttensorcore_utilizationbuffer_transfer_latencyhost_to_device_transfer_latencydevice_to_host_transfer_latencycollective_e2e_latency
$ tpu-info --metric duty_cycle_percent hbm_usage
L'output dovrebbe essere simile al seguente:
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 |
Elenca metriche
Utilizza il flag --list_metrics per visualizzare tutte le metriche supportate che possono essere richieste con il flag --metric.
$ tpu-info --list_metrics
L'output dovrebbe essere simile al seguente:
╭─ 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 │
╰─────────────────────────────────────────────────────────────────────────────────────────────────╯
Metriche degli stream
La modalità di streaming aggiorna periodicamente e visualizza statistiche di utilizzo aggiornate. Per trasmettere in streaming le metriche LibTPU, aggiungi il flag --streaming al comando tpu-info. Utilizza il flag --rate per controllare la cadenza dello streaming in secondi.
Utilizza il seguente comando per trasmettere in streaming le metriche tpu-info predefinite con l'interfaccia a riga di comando:
# Refresh metrics every 2 seconds
tpu-info --streaming --rate 2
L'output è simile al seguente:
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 |
Metriche TPU-Z
TPU-Z è una funzionalità di telemetria e debug per le TPU. Fornisce informazioni dettagliate sullo stato di runtime per tutti i core TPU collegati a un host. La funzionalità viene fornita tramite il modulo tpuz, che fa parte del modulo libtpu.sdk nell'SDK Python libtpu. Il modulo fornisce un'istantanea
dello stato di ogni core.
Il caso d'uso principale di TPU-Z è la diagnosi di blocchi o deadlock nei workload TPU distribuiti. Puoi eseguire query sul servizio TPU-Z sugli host per acquisire lo stato di ogni core, confrontando i contatori di programma, le posizioni HLO e gli ID esecuzione di tutti i core per identificare le anomalie.
Utilizza il seguente comando per visualizzare le metriche TPU-Z utilizzando l'interfaccia a riga di comando:
tpu-info --metric core_state
tpu-info --metric sequencer_state
tpu-info --metric sequencer_state_detailed
tpu-info --metric queued_program
L'output deve includere le tabelle core_state, sequencer_state, sequencer_state_detailed e queued_programs.
Informazioni sullo stato di base
La tabella Core State Information (core_state) fornisce informazioni sui core di un determinato chip. Le TPU hanno uno o due core per chip, a seconda della generazione.
| Campo | Descrizione | Valori di esempio |
|---|---|---|
| ID chip | L'ID del chip a cui appartiene il core. | 0 |
| ID core globale | L'ID univoco del core all'interno dell'intero sistema TPU. | 1 |
| Tipo di core | Il tipo di core TPU. | "TPU_CORE_TYPE_TENSOR_CORE""TPU_CORE_TYPE_SPARSE_CORE" |
| Server xdb in esecuzione | Indica se il server Accelerator Debugger (XDB) è in esecuzione su un core TPU specifico. | True |
L'output dovrebbe essere simile alla seguente tabella:
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 |
Informazioni sullo stato del sequencer
La tabella Sequencer State Information (sequencer_state) fornisce informazioni sullo stato di un sequencer su un core. Un sequencer è un'unità di controllo all'interno di un core TPU responsabile del recupero, della decodifica e dell'orchestrazione dell'esecuzione delle istruzioni. Possono esserci più sequencer per un singolo core.
| Metrica | Descrizione | Valori di esempio |
|---|---|---|
| ID chip | L'ID del chip a cui appartiene il core. | 0 |
| ID core globale | L'ID univoco del core all'interno dell'intero sistema TPU. | 1 |
| Contatore di programma | L'indirizzo di memoria dell'istruzione che deve essere eseguita dal sequencer. | 15390 |
| Tracemark | L'ID di lancio del programma corrente o più recente. Questo campo è assente se non applicabile. | 2147483647 |
| ID programma | L'ID associato a un'istanza specifica di un programma avviato per l'esecuzione su un core TPU. | 3230481660274331500 |
| ID esecuzione | L'ID esecuzione associato al programma. | 1150 |
| Tipo di sequenza | Il tipo di sequencer. | "TPU_SEQUENCER_TYPE_SPARSE_CORE_SEQUENCER""TPU_SEQUENCER_TYPE_SPARSE_CORE_TILE_EXECUTE_CORE_SEQUENCER" |
L'output dovrebbe essere simile alla seguente tabella:
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 |
Informazioni sullo stato del sequencer (dettagliate)
La tabella Sequencer State Information (detailed) (sequencer_state_detailed) fornisce tutte le informazioni della tabella Sequencer State Information (sequencer_state), insieme alle seguenti metriche aggiuntive:
| Metrica | Descrizione | Valori di esempio |
|---|---|---|
| Dettagli HLO | Informazioni dettagliate sull'HLO, se disponibili. | [] |
| ID esecuzione programma in coda | L'ID esecuzione di questo programma in coda. | 81 |
| ID lancio del programma in coda | L'ID di lancio di questo programma in coda. | 1394130914 |
| Errore di base | Contiene eventuali messaggi di errore per questo core. Questo campo è assente se non sono presenti errori. | "Failed to parse launch id: 0xdcf36153" |
| Località HLO | Dati sulla posizione dell'ottimizzatore di alto livello (HLO). | "no HLO mapping""HLO: fusion.11; HLO computation: main.126_spmd" |
L'output dovrebbe essere simile alla seguente tabella:
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 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
Programmi in coda
La tabella Programmi in coda (queued_programs) fornisce l'elenco dei programmi
in coda per l'esecuzione.
| Metrica | Descrizione | Valori di esempio |
|---|---|---|
| ID chip | L'ID del chip a cui appartiene il core. | 0 |
| Global Core | L'ID univoco del core all'interno dell'intero sistema TPU. | 1 |
| Program Counter:Tag | L'indirizzo di memoria dell'istruzione che deve essere eseguita dal sequencer. | 15390 |
| Tracemark | L'ID di lancio del programma corrente o più recente. Questo campo è assente se non applicabile. | 2147483647 |
| ID programma | L'ID associato a un'istanza specifica di un programma avviato per l'esecuzione su un core TPU. | 3230481660274331500 |
| ID esecuzione | L'ID esecuzione associato al programma. | 1150 |
| Tipo di sequenza | Il tipo di sequencer. | "\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\\...\\ |
| ... | ... | ... | ... | ... | ... | ... |
Funzionalità o metriche mancanti
Se non riesci a visualizzare alcune funzionalità o metriche, la causa più comune è una versione di libtpu obsoleta. Le funzionalità e le metriche di tpu-info sono incluse nelle release di libtpu e le versioni obsolete potrebbero non includere nuove funzionalità e metriche.
Per verificare che la versione di tpu-info sia compatibile con il tuo ambiente, utilizza il flag --version o -v:
$ tpu-info --version
L'output seguente mostra un esempio di ambiente compatibile:
- tpu-info version: 0.5.1
- libtpu version: 0.0.18
- accelerator type: v6e
L'output seguente mostra un esempio di ambiente incompatibile:
- tpu-info version: 0.5.1
- libtpu version: N/A (incompatible environment)
- accelerator type: N/A (incompatible environment)
Se utilizzi una versione obsoleta, esegui l'aggiornamento all'ultima versione di libtpu:
pip install --upgrade libtpu