magic-trace - Intel PT Tracing de Alta Resolução
magic-trace (por Jane Street) captura e exibe traços de execução de alta resolução usando Intel Processor Trace (Intel PT). Onde um profiler de amostragem diz aonde o tempo vai em média, magic-trace registra o fluxo de controle real — cada entrada e saída de função — pelos últimos poucos milissegundos, em resolução de nanosegundo. Isso o torna únicamente adequado para eventos raros e sensíveis a latência: aquele requisição em dez mil que levou 40ms, onde um perfil médio não mostra nada.
Requisitos
- Intel CPU com suporte a Processor Trace (maioria dos Intel modernos)
- Linux com perf e PT habilitado
- Root ou configuração apropriada de
perf_event_paranoid
- Binários com frame pointers / símbolos para saída legível
Instalação
| Método | Comando |
|---|
| Binary | baixe magic-trace do GitHub Releases |
| opam (OCaml) | opam install magic_trace |
| Permissões | sysctl kernel.perf_event_paranoid=-1 (ou 1) |
| Verificar | magic-trace --help |
Dois Modos de Captura
| Modo | Comando | Uso |
|---|
| Anexar a rodando | magic-trace attach -pid <pid> | Serviço ao vivo |
| Executar um comando | magic-trace run ./my-program | Run reproduzível |
# Anexar, capturar em Ctrl-C, escrever um traço
sudo magic-trace attach -pid $(pgrep -n myservice)
Snapshot Triggers
A ideia central: manter um buffer rolando e fazer snapshot quando algo interessante acontece.
| Trigger | Como |
|---|
| Manual | Pressione Ctrl-C enquanto anexado |
| Magic breakpoint | App chama um símbolo designado para desencadear um snapshot |
| Timer | Capturar após uma duração fixa |
| Symbol trigger | -trigger <symbol> para snapshot em uma chamada de função |
# Fazer snapshot sempre que uma função específica é atingida
sudo magic-trace attach -pid <pid> -trigger 'handle_slow_path'
Porque o buffer mantém os anteriores poucos milissegundos, você vê o que levou ao evento, não apenas o evento em si.
Visualizando Traços
magic-trace emite um traço visualizável na UI Perfetto.
| Passo | Ação |
|---|
| 1 | Captura produz trace.fxt (ou similar) |
| 2 | Abrir ui.perfetto.dev |
| 3 | Carregar o arquivo de traço |
| 4 | Zoom no intervalo microsecond de interesse |
| 5 | Ler a sequência exata de chamada e durações |
| Controle Perfetto | Faz |
|---|
W/S | Zoom in/out |
A/D | Pan |
| Click em um slice | Detalhe de duração e função |
| Selecionar um intervalo | Sumário do que rodou |
O que Você Pode Ver
| Pergunta | Resposta de magic-trace |
|---|
| Qual função causou esse spike de 40ms? | Chamada exata, duração exata |
| Tomamos um branch inesperado? | Fluxo de controle completo, visível |
| Para onde o tempo foi dentro de um requisição? | Breakdown de nanosegundo |
| Era uma syscall, um lock, ou compute? | A sequência de chamada mostra |
Opções Vale Conhecer
| Flag | Propósito |
|---|
-multi-thread | Rastrear todas as threads |
-duration | Duração da janela de captura |
-trigger SYMBOL | Fazer snapshot em um símbolo |
-full-execution | Rastrear uma run curta inteira |
-output FILE | Caminho de saída de traço |
Limitações
| Limitação | Nota |
|---|
| Apenas Intel | Requer Intel PT (sem AMD/ARM) |
| Janela curta | Milissegundos, não minutos |
| Qualidade de símbolo | Binários stripped rendem traços pobres |
| Overhead | Baixo mas não zero enquanto rastreando |
magic-trace vs Ferramentas Relacionadas
| Aspecto | magic-trace | perf | Perfetto |
|---|
| Dados | Fluxo de controle completo (Intel PT) | Stacks amostrados | Timeline system-wide |
| Resolução | Nanosegundos | Intervalo de amostra | Event-level |
| Janela | Últimos poucos ms | Toda a run | Configurável |
| Melhor para | Spikes de latência raros | Hot paths médios | Timelines system-wide |
Use perf para hot paths médios, Perfetto para timelines system-wide, e magic-trace quando você precisa da história exata de um evento lento raro.
Recursos
