O Deno inclui suporte integrado a profiling de CPU do V8, o que ajuda você a identificar gargalos de performance no seu código. Use a flag --cpu-prof para capturar um profile de CPU durante a execução do programa:

deno run --cpu-prof your_script.ts
# or with deno eval
deno eval --cpu-prof "for (let i = 0; i < 1e8; i++) {}"

Quando seu programa termina, o Deno escreve um arquivo .cpuprofile no diretório atual (por exemplo, CPU.1769017882255.25986.cpuprofile). Esse arquivo pode ser carregado no Chrome DevTools (aba Performance) ou em outros visualizadores de profile do V8 para análise.

Flags de profiling de CPU

Flag Descrição
--cpu-prof Ativa profiling de CPU. O profile é escrito em disco ao sair.
--cpu-prof-dir=<DIR> Diretório onde o profile de CPU será escrito. O padrão é o diretório atual. Ativa --cpu-prof implicitamente.
--cpu-prof-name=<NAME> Nome do arquivo do profile de CPU. O padrão é CPU.<timestamp>.<pid>.cpuprofile.
--cpu-prof-interval=<MICROSECONDS> Intervalo de amostragem em microssegundos. O padrão é 1000 (1ms). Valores menores dão mais detalhes, mas arquivos maiores.
--cpu-prof-md Gera um relatório Markdown legível por humanos junto do arquivo .cpuprofile.
--cpu-prof-flamegraph Gera um flamegraph SVG interativo junto do arquivo .cpuprofile.

:::note

Profiles de CPU reportam números de linha do código JavaScript transpilado, não do código-fonte TypeScript original. Esta é uma limitação do profiler do V8. Em arquivos TypeScript, os números de linha reportados podem não corresponder diretamente ao seu código-fonte.

:::

Personalizando a saída do profile

Por padrão, profiles são escritos no diretório atual com um nome de arquivo gerado automaticamente. Você pode controlar onde e como os profiles são salvos:

# Save profiles to a specific directory
deno run --cpu-prof --cpu-prof-dir=./profiles your_script.ts

# Use a custom filename
deno run --cpu-prof --cpu-prof-name=my-profile.cpuprofile your_script.ts

# Increase sampling frequency for more detail (default: 1000μs)
deno run --cpu-prof --cpu-prof-interval=100 your_script.ts

Um --cpu-prof-interval menor captura mais amostras por segundo, dando granularidade mais fina ao custo de arquivos de profile maiores. O padrão de 1000 microssegundos (1ms) é um bom equilíbrio para a maioria dos casos de uso. Para funções de curta duração que você quer capturar em detalhes, tente 100 (0.1ms).

Analisando profiles no Chrome DevTools

Para analisar o arquivo .cpuprofile:

  1. Abra o Chrome DevTools (F12)
  2. Vá para a aba Performance
  3. Clique no botão Load profile (ícone de seta para cima)
  4. Selecione seu arquivo .cpuprofile

O DevTools exibirá um flame chart e uma divisão detalhada de onde o tempo foi gasto na sua aplicação.

Exemplo: relatório Markdown

A flag --cpu-prof-md gera um resumo em Markdown fácil de ler sem carregar o profile no DevTools:

deno run -A --cpu-prof --cpu-prof-md server.js

Isso cria tanto um arquivo .cpuprofile quanto um arquivo .md com um relatório como:

# CPU Profile

| Duration | Samples | Interval | Functions |
| -------- | ------- | -------- | --------- |
| 833.06ms | 641     | 1000us   | 10        |

**Top 10:** `op_crypto_get_random_values` 98.5%, `(garbage collector)` 0.7%,
`getRandomValues` 0.6%, `assertBranded` 0.2%

## Hot Functions (Self Time)

| Self% |     Self | Total% |    Total | Function                      | Location          |
| ----: | -------: | -----: | -------: | ----------------------------- | ----------------- |
| 98.5% | 533.00ms |  98.5% | 533.00ms | `op_crypto_get_random_values` | [native code]     |
|  0.7% |   4.00ms |   0.7% |   4.00ms | `(garbage collector)`         | [native code]     |
|  0.6% |   3.00ms |   0.6% |   3.00ms | `getRandomValues`             | 00_crypto.js:5274 |
|  0.2% |   1.00ms |   0.2% |   1.00ms | `assertBranded`               | 00_webidl.js:1149 |

## Call Tree (Total Time)

| Total% |    Total | Self% |     Self | Function                      | Location          |
| -----: | -------: | ----: | -------: | ----------------------------- | ----------------- |
|  16.8% |  91.00ms | 16.8% |  91.00ms | `(anonymous)`                 | server.js:1       |
|   0.6% |   3.00ms |  0.6% |   3.00ms | `getRandomValues`             | 00_crypto.js:5274 |
|  98.5% | 533.00ms | 98.5% | 533.00ms | `op_crypto_get_random_values` | [native code]     |

## Function Details

## `op_crypto_get_random_values`

[native code] | Self: 98.5% (533.00ms) | Total: 98.5% (533.00ms) | Samples: 533

O relatório inclui:

  • Resumo: duração total, contagem de amostras, intervalo de amostragem e contagem de funções
  • Top 10: visão rápida das funções mais caras
  • Hot Functions: funções ordenadas por self time (tempo gasto na própria função, excluindo chamadas)
  • Call Tree: visão hierárquica mostrando a call stack e a distribuição de tempo
  • Function Details: detalhamento por função com contagem de amostras

Exemplo: flamegraph interativo

A flag --cpu-prof-flamegraph gera um flamegraph SVG interativo e autocontido que você pode abrir diretamente em um navegador — sem ferramentas externas:

deno run --cpu-prof --cpu-prof-flamegraph your_script.ts

Isso cria tanto um arquivo .cpuprofile quanto um arquivo .svg. Abra o SVG em qualquer navegador para explorar o profile interativamente:

  • Clique em qualquer frame para dar zoom nessa subárvore
  • Botão Reset Zoom para restaurar a visualização completa
  • Ctrl+F ou o botão Search para busca de função baseada em regex com realce e percentual correspondente
  • Checkbox Invert para virar para um icicle graph (raiz no topo)
  • Passe o mouse sobre qualquer frame para ver o nome da função e a contagem de amostras

O flamegraph também funciona com deno eval:

deno eval --cpu-prof --cpu-prof-flamegraph "for (let i = 0; i < 1e8; i++) {}"

Dicas de profiling

  • Faça profile de cargas representativas: para servidores HTTP, envie tráfego realista ao servidor antes de pará-lo — o profile só captura o que acontece enquanto o programa está rodando.
  • Use self time vs. total time: em relatórios de profile, self time é o tempo gasto no próprio código de uma função, enquanto total time inclui o tempo nas funções que ela chama. Self time alto aponta para o gargalo real; total time alto com self time baixo significa que a função delega para algo caro.
  • Compare antes e depois: salve profiles com valores descritivos em --cpu-prof-name (por exemplo, before-optimization.cpuprofile) para comparar profiles lado a lado no DevTools depois de fazer mudanças.
  • Combine formatos de saída: você pode usar --cpu-prof-md e --cpu-prof-flamegraph juntos para obter as três saídas (.cpuprofile, .md e .svg) em uma única execução:
    deno run --cpu-prof --cpu-prof-md --cpu-prof-flamegraph your_script.ts
  • Filtre ruído: programas de curta duração podem mostrar overhead de inicialização (carregamento de módulos, compilação JIT) dominando o profile. Para resultados mais precisos, garanta que o código que você quer perfilar rode tempo suficiente para coletar amostras significativas.