Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

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 de la bibliothèque libtpu, y compris l'utilisation de la mémoire et le cycle de service. Il accepte les instantanés statiques ponctuels et 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'il ne manque aucune métrique ni fonctionnalité. 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 des 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. 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 exécutés 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 courantes acceptées :

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 pouvant ê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

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 de diffusion en continu en secondes.

Utilisez 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 via le module tpuz, qui fait partie du module libtpu.sdk dans le SDK Python libtpu. Le module fournit un instantané de l'état de chaque cœur.

Le principal cas d'utilisation de TPU-Z est le diagnostic des blocages ou des 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 pour identifier les anomalies.

Utilisez 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 tables core_state, sequencer_state, sequencer_state_detailed et queued_programs.

Informations sur l'état de base

La table d'informations sur l'état des cœurs (core_state) fournit des informations sur les cœurs d'une puce donnée. Les TPU ont 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 principal global	Identifiant unique du cœur dans l'ensemble du système TPU.	`1`
Type de cœur	Type de cœur de 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 de TPU spécifique.	`True`

Le résultat doit ressembler au tableau suivant :

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 de TPU chargée de récupérer, de décoder et d'orchestrer l'exécution des instructions. Il peut y avoir plusieurs séquenceurs pour un même cœur.

Métrique	Description	Exemples de valeur
ID de puce électronique	ID de la puce à laquelle appartient le cœur.	`0`
ID principal global	Identifiant 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 exécution sur un cœur de 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 au tableau suivant :

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 "Informations sur l'état du séquenceur (détaillées)" (sequencer_state_detailed) fournit toutes les informations de la table "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 de l'optimisation de haut niveau	Informations détaillées sur l'OLH, si disponibles.	`[]`
ID de l'exécution du programme en file d'attente	ID d'exécution de ce programme mis en file d'attente.	`81`
ID de lancement du programme mis en file d'attente	ID de lancement de ce programme mis en file d'attente.	`1394130914`
Erreur de base	Contient 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 de l'OLH	Informations de localisation de l'optimiseur de haut niveau (HLO).	`"no HLO mapping"` `"HLO: fusion.11; HLO computation: main.126_spmd"`

Le résultat doit ressembler au tableau suivant :

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 "Programmes mis en file d'attente" (queued_programs) fournit la liste des programmes mis en file d'attente pour exécution.

Métrique	Description	Exemples de valeur
ID de puce électronique	ID de la puce à laquelle appartient le cœur.	`0`
Focus sur le monde entier	Identifiant 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 exécution sur un cœur de 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 courante est une version obsolète de libtpu. Les fonctionnalités et les métriques de tpu-info sont incluses dans les versions de libtpu. 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, installez la dernière version de libtpu :

pip install --upgrade libtpu