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

Surveiller avec la CLI tpu-info

La CLI tpu-info est un outil permettant de détecter les appareils Cloud TPU et de lire les métriques d'exécution à partir de la bibliothèque libtpu, y compris l'utilisation de la mémoire et le cycle de service. Elle est compatible avec les instantanés statiques et ponctuels, ainsi qu'avec le streaming en direct pour surveiller les métriques en continu.

Installation

Installez la dernière version à l'aide de pip :

pip install tpu-info

Vous pouvez également installer tpu-info à partir de la source :

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

Si vous avez déjà installé une version de tpu-info, assurez-vous qu'elle est compatible avec votre environnement et qu'aucune métrique ni fonctionnalité ne manque. Pour en savoir plus, consultez Fonctionnalités ou métriques manquantes.

Accéder aux métriques LibTPU standards à l'aide de la CLI

Exécutez la commande suivante pour afficher les métriques tpu-info par défaut avec la CLI :

tpu-info

Le résultat ressemble à ce qui suit :

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 |

Utilisation

Pour afficher les données d'utilisation actuelles du TPU, tpu-info nécessite une charge de travail TPU en cours d'exécution avec un framework de ML compatible, tel que JAX ou PyTorch/XLA. Vous pouvez exécuter la commande tpu-info dans votre terminal avec les options suivantes.

Processus

Utilisez l'option --process ou -p pour afficher des informations sur les processus en cours d'exécution sur le TPU.

$ tpu-info --process

Le résultat doit ressembler à ce qui suit :

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      |

Métrique

Utilisez l'option --metric pour afficher des métriques spécifiques. Vous pouvez spécifier plusieurs métriques séparées par des espaces. Voici quelques métriques compatibles courantes :

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

Le résultat doit ressembler à ce qui suit :

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 |

Répertorier les statistiques

Utilisez l'option --list_metrics pour afficher toutes les métriques compatibles qui peuvent être demandées avec l'option --metric.

$ tpu-info --list_metrics

Le résultat doit ressembler à ce qui suit :

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

Métriques de flux continu

Le mode de streaming actualise et affiche régulièrement des statistiques d'utilisation à jour. Pour diffuser les métriques LibTPU, ajoutez l'option --streaming à la commande tpu-info. Utilisez l'option --rate pour contrôler la cadence du streaming en secondes.

Exécutez la commande suivante pour diffuser les métriques tpu-info par défaut avec la CLI :

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

Le résultat ressemble à ce qui suit :

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 |

Métriques TPU-Z

TPU-Z est un outil de télémétrie et de débogage pour les TPU. Il fournit des informations détaillées sur l'état d'exécution de tous les cœurs TPU associés à un hôte. La fonctionnalité est fournie par le tpuz module, qui fait partie du libtpu.sdk module dans le libtpu SDK Python. Le module fournit un instantané de l'état de chaque cœur.

Le principal cas d'utilisation de TPU-Z consiste à diagnostiquer les blocages ou les interblocages dans les charges de travail TPU distribuées. Vous pouvez interroger le service TPU-Z sur les hôtes pour capturer l'état de chaque cœur, en comparant les compteurs de programme, les emplacements HLO et les ID d'exécution sur tous les cœurs afin d'identifier les anomalies.

Exécutez la commande suivante pour afficher les métriques TPU-Z à l'aide de la CLI :

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

Le résultat doit inclure les core_state, sequencer_state, sequencer_state_detailed, et queued_programs tables.

Informations sur l'état du cœur

La table d'informations sur l'état du cœur (core_state) fournit des informations sur les cœurs d'une puce donnée. Les TPU comportent un ou deux cœurs par puce, selon la génération.

Champ	Description	Exemples de valeur
ID de puce électronique	ID de la puce à laquelle appartient le cœur.	`0`
ID de cœur global	ID unique du cœur dans l'ensemble du système TPU.	`1`
Type de cœur	Type de cœur TPU.	`"TPU_CORE_TYPE_TENSOR_CORE"` `"TPU_CORE_TYPE_SPARSE_CORE"`
Serveur xdb en cours d'exécution	Indique si le serveur Accelerator Debugger (XDB) est en cours d'exécution sur un cœur TPU spécifique.	`True`

Le résultat doit ressembler à la table suivante :

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       |

Informations sur l'état du séquenceur

La table d'informations sur l'état du séquenceur (sequencer_state) fournit des informations sur l'état d'un séquenceur sur un cœur. Un séquenceur est une unité de contrôle au sein d'un cœur TPU chargée d'extraire, de décoder et d'orchestrer l'exécution des instructions. Un même cœur peut comporter plusieurs séquenceurs.

Métrique	Description	Exemples de valeur
ID de puce électronique	ID de la puce à laquelle appartient le cœur.	`0`
ID de cœur global	ID unique du cœur dans l'ensemble du système TPU.	`1`
Compteur de programme	Adresse mémoire de l'instruction à exécuter par le séquenceur.	`15390`
Tracemark	ID de lancement du programme actuel ou le plus récent. Ce champ est absent s'il n'est pas applicable.	`2147483647`
ID du programme	ID associé à une instance spécifique d'un programme lancé pour être exécuté sur un cœur TPU.	`3230481660274331500`
ID de l'exécution	ID d'exécution associé au programme.	`1150`
Type de séquence	Type de séquenceur.	`"TPU_SEQUENCER_TYPE_SPARSE_CORE_SEQUENCER"` `"TPU_SEQUENCER_TYPE_SPARSE_CORE_TILE_EXECUTE_CORE_SEQUENCER"`

Le résultat doit ressembler à la table suivante :

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   |

Informations sur l'état du séquenceur (détaillées)

La table d'informations sur l'état du séquenceur (détaillées) (sequencer_state_detailed) fournit toutes les informations de la table d'informations sur l'état du séquenceur (sequencer_state), ainsi que les métriques supplémentaires suivantes :

Métrique	Description	Exemples de valeur
Détails HLO	Informations HLO détaillées, si disponibles.	`[]`
ID d'exécution du programme en file d'attente	ID d'exécution de ce programme en file d'attente.	`81`
ID de lancement du programme en file d'attente	ID de lancement de ce programme en file d'attente.	`1394130914`
Erreur de base	Contient tous les messages d'erreur pour ce cœur. Ce champ est absent s'il n'y a pas d'erreur.	`"Failed to parse launch id: 0xdcf36153"`
Emplacement HLO	Informations sur l'emplacement de l'optimiseur de haut niveau (HLO).	`"no HLO mapping"` `"HLO: fusion.11; HLO computation: main.126_spmd"`

Le résultat doit ressembler à la table suivante :

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

Programmes en file d'attente

La table des programmes en file d'attente (queued_programs) fournit la liste des programmes en file d'attente pour l'exécution.

Métrique	Description	Exemples de valeur
ID de puce électronique	ID de la puce à laquelle appartient le cœur.	`0`
Cœur global	ID unique du cœur dans l'ensemble du système TPU.	`1`
Compteur de programme : balise	Adresse mémoire de l'instruction à exécuter par le séquenceur.	`15390`
Tracemark	ID de lancement du programme actuel ou le plus récent. Ce champ est absent s'il n'est pas applicable.	`2147483647`
ID du programme	ID associé à une instance spécifique d'un programme lancé pour être exécuté sur un cœur TPU.	`3230481660274331500`
ID de l'exécution	ID d'exécution associé au programme.	`1150`
Type de séquence	Type de séquenceur.	`"\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\\...\\ |
| ...     | ...         | ...                 | ...       | ...         | ...    | ...                                |

Fonctionnalités ou métriques manquantes

Si vous ne parvenez pas à afficher certaines fonctionnalités ou métriques, la cause la plus fréquente est une version obsolète de libtpu. Les fonctionnalités et les métriques de tpu-info sont incluses dans les versions libtpu, et les versions obsolètes peuvent ne pas inclure les nouvelles fonctionnalités et métriques.

Pour vérifier que la version de tpu-info est compatible avec votre environnement, utilisez l'option --version ou -v :

$ tpu-info --version

Le résultat suivant montre un exemple d'environnement compatible :

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

Le résultat suivant montre un exemple d'environnement incompatible :

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

Si vous utilisez une version obsolète, passez à la dernière version de libtpu :

pip install --upgrade libtpu