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

Monitorar com a CLI tpu-info

A CLI tpu-info é uma ferramenta para detectar dispositivos do Cloud TPU e ler métricas de tempo de execução da biblioteca libtpu, incluindo uso da memória e ciclo de trabalho. Ele é compatível com snapshots estáticos e únicos, além de transmissões ao vivo para monitorar métricas continuamente.

Instalação

Instale a versão mais recente usando pip:

pip install tpu-info

Como alternativa, instale o tpu-info da origem:

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

Se você já instalou uma versão do tpu-info, verifique se ela é compatível com seu ambiente e se não está faltando métricas e recursos. Para mais informações, consulte Recursos ou métricas ausentes.

Acessar métricas padrão da LibTPU usando a CLI

Use o seguinte comando para conferir as métricas padrão do tpu-info com a CLI:

tpu-info

O resultado será o seguinte:

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 |

Uso

Para conferir os dados atuais de utilização da TPU, o tpu-info exige uma carga de trabalho de TPU em execução com um framework de ML compatível, como JAX ou PyTorch/XLA. Execute o comando tpu-info no terminal com as flags a seguir.

Processo

Use a flag --process ou -p para mostrar informações sobre os processos em execução na TPU.

$ tpu-info --process

A saída será parecida com esta:

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étrica

Use a flag --metric para mostrar métricas específicas. É possível especificar várias métricas separadas por espaços. Algumas métricas comuns com suporte são:

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

A saída será parecida com esta:

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 |

Listar métricas

Use a flag --list_metrics para mostrar todas as métricas compatíveis que podem ser solicitadas com a flag --metric.

$ tpu-info --list_metrics

A saída será parecida com esta:

╭─ 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étricas de stream

O modo de streaming atualiza e mostra periodicamente as estatísticas de utilização atualizadas. Para transmitir as métricas da LibTPU, adicione a flag --streaming ao comando tpu-info. Use a flag --rate para controlar a cadência do streaming em segundos.

Use o seguinte comando para transmitir as métricas padrão do tpu-info com a CLI:

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

O resultado será o seguinte:

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étricas do TPU-Z

O TPU-Z é uma ferramenta de telemetria e depuração para TPUs. Ele fornece informações detalhadas sobre o status de tempo de execução de todos os núcleos de TPU conectados a um host. A funcionalidade é fornecida pelo módulo tpuz, que faz parte do módulo libtpu.sdk no SDK do Python libtpu. O módulo fornece um snapshot do estado de cada núcleo.

O principal caso de uso do TPU-Z é diagnosticar travamentos ou impasses em cargas de trabalho distribuídas de TPU. É possível consultar o serviço TPU-Z em hosts para capturar o estado de cada núcleo, comparando os contadores de programa, os locais de HLO e os IDs de execução em todos os núcleos para identificar anomalias.

Use o seguinte comando para conferir as métricas do TPU-Z usando a CLI:

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

A saída precisa incluir as tabelas core_state, sequencer_state, sequencer_state_detailed e queued_programs.

Informações principais do estado

A tabela de informações de estado do núcleo (core_state) fornece informações sobre os núcleos de um determinado chip. As TPUs têm um ou dois núcleos por chip, dependendo da geração.

Campo	Descrição	Exemplos de valores
ID do chip	O ID do chip a que o núcleo pertence.	`0`
ID global principal	O ID exclusivo do núcleo em todo o sistema de TPU.	`1`
Tipo de núcleo	O tipo do núcleo da TPU.	`"TPU_CORE_TYPE_TENSOR_CORE"` `"TPU_CORE_TYPE_SPARSE_CORE"`
Servidor xdb em execução	Indica se o servidor do depurador de aceleradores (XDB) está sendo executado em um núcleo de TPU específico.	`True`

A saída será parecida com esta tabela:

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       |

Informações de estado do sequenciador

A tabela de informações de estado do sequenciador (sequencer_state) fornece informações sobre o estado de um sequenciador em um núcleo. Um sequenciador é uma unidade de controle em um núcleo de TPU responsável por buscar, decodificar e orquestrar a execução de instruções. Pode haver vários sequenciadores para um único núcleo.

Métrica	Descrição	Exemplos de valores
ID do chip	O ID do chip a que o núcleo pertence.	`0`
ID global principal	O ID exclusivo do núcleo em todo o sistema de TPU.	`1`
Contador de programa	O endereço de memória da instrução a ser executada pelo sequenciador.	`15390`
Tracemark	O ID de lançamento do programa atual ou mais recente. Esse campo fica ausente se não for aplicável.	`2147483647`
ID do programa	O ID associado a uma instância específica de um programa sendo iniciado para execução em um núcleo de TPU.	`3230481660274331500`
ID da execução	O ID da execução associado ao programa.	`1150`
Tipo de sequência	O tipo de sequenciador.	`"TPU_SEQUENCER_TYPE_SPARSE_CORE_SEQUENCER"` `"TPU_SEQUENCER_TYPE_SPARSE_CORE_TILE_EXECUTE_CORE_SEQUENCER"`

A saída será parecida com esta tabela:

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   |

Informações detalhadas sobre o estado do sequenciador

A tabela "Informações detalhadas sobre o estado do sequenciador" (sequencer_state_detailed) fornece todas as informações da tabela "Informações sobre o estado do sequenciador" (sequencer_state), além das seguintes métricas:

Métrica	Descrição	Exemplos de valores
Detalhes do HLO	Informações detalhadas sobre o HLO, se disponíveis.	`[]`
ID da execução do programa na fila	O ID da execução do programa enfileirado.	`81`
ID do lançamento do programa na fila	O ID de lançamento do programa na fila.	`1394130914`
Erro principal	Contém mensagens de erro para esse núcleo. Esse campo fica ausente se não há erros.	`"Failed to parse launch id: 0xdcf36153"`
Localização do HLO	Informações de local do High-level Optimizer (HLO).	`"no HLO mapping"` `"HLO: fusion.11; HLO computation: main.126_spmd"`

A saída será parecida com esta tabela:

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

Programas na fila

A tabela "Programas na fila" (queued_programs) mostra a lista de programas na fila para execução.

Métrica	Descrição	Exemplos de valores
ID do chip	O ID do chip a que o núcleo pertence.	`0`
Global Core	O ID exclusivo do núcleo em todo o sistema de TPU.	`1`
Contador de programa:tag	O endereço de memória da instrução a ser executada pelo sequenciador.	`15390`
Tracemark	O ID de lançamento do programa atual ou mais recente. Esse campo fica ausente se não for aplicável.	`2147483647`
ID do programa	O ID associado a uma instância específica de um programa sendo iniciado para execução em um núcleo de TPU.	`3230481660274331500`
ID da execução	O ID da execução associado ao programa.	`1150`
Tipo de sequência	O tipo de sequenciador.	`"\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\\...\\ |
| ...     | ...         | ...                 | ...       | ...         | ...    | ...                                |

Recursos ou métricas ausentes

Se você não conseguir acessar alguns recursos ou métricas, o motivo mais comum é uma versão desatualizada do libtpu. Os recursos e as métricas do tpu-info estão incluídos nas versões do libtpu, e as versões desatualizadas podem não ter novos recursos e métricas.

Para verificar se a versão do tpu-info é compatível com seu ambiente, use a flag --version ou -v:

$ tpu-info --version

A saída a seguir mostra um exemplo de ambiente compatível:

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

A saída a seguir mostra um exemplo de ambiente incompatível:

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

Se você estiver usando uma versão desatualizada, atualize para a versão mais recente do libtpu:

pip install --upgrade libtpu