magic-trace - Cheatsheet del Tracing ad Alta Risoluzione di Intel PT
magic-trace (di Jane Street) cattura e visualizza tracce di esecuzione ad alta risoluzione usando Intel Processor Trace (Intel PT). Dove un profiler di sampling ti dice dove va il tempo in media, magic-trace registra il flusso di controllo effettivo — ogni voce e uscita di funzione — per l”ultimo millisecondo, a risoluzione nanosecondo. Questo la rende unica per gli eventi latenti e sensibili alla latenza: la richiesta uno su diecimila che ha impiegato 40ms, dove un profilo mediano non ti mostra nulla.
Requirements
- CPU Intel con supporto Processor Trace (la maggior parte di Intel moderno)
- Linux con perf e PT abilitato
- Root o impostazione
perf_event_paranoid appropriata
- Binari con frame pointer / simboli per output leggibile
Installation
| Method | Command |
|---|
| Binary | download magic-trace da GitHub Releases |
| opam (OCaml) | opam install magic_trace |
| Permissions | sysctl kernel.perf_event_paranoid=-1 (o 1) |
| Verify | magic-trace --help |
Two Capture Modes
| Mode | Command | Use |
|---|
| Attach to running | magic-trace attach -pid <pid> | Servizio live |
| Run a command | magic-trace run ./my-program | Esecuzione riproducibile |
# Attach, capture on Ctrl-C, write a trace
sudo magic-trace attach -pid $(pgrep -n myservice)
Snapshot Triggers
L”idea principale: tieni un buffer di scorrimento e snapshot quando succede qualcosa di interessante.
| Trigger | How |
|---|
| Manual | Premi Ctrl-C mentre collegato |
| Magic breakpoint | L”app chiama un simbolo designato per attivare uno snapshot |
| Timer | Cattura dopo una durata fissa |
| Symbol trigger | -trigger <symbol> per snapshot su una chiamata di funzione |
# Snapshot whenever a specific function is hit
sudo magic-trace attach -pid <pid> -trigger 'handle_slow_path'
Poiché il buffer contiene il precedente millisecondo di pochi, vedi ciò che ha portato all”evento, non solo l”evento stesso.
Viewing Traces
magic-trace emette una traccia visualizzabile nell”UI di Perfetto.
| Step | Action |
|---|
| 1 | Capture produce trace.fxt (o simile) |
| 2 | Apri ui.perfetto.dev |
| 3 | Carica il file di traccia |
| 4 | Zoom nell”intervallo microsecondo di interesse |
| 5 | Leggi la sequenza di chiamata esatta e le durate |
| Perfetto control | Does |
|---|
W/S | Zoom in/out |
A/D | Pan |
| Click a slice | Dettagli di durata e funzione |
| Select a range | Riepilogo di ciò che è stato eseguito |
What You Can See
| Question | magic-trace answer |
|---|
| Quale funzione ha causato questo picco di 40ms? | Chiamata esatta, durata esatta |
| Abbiamo preso un ramo inaspettato? | Flusso di controllo completo, visibile |
| Dove è andato il tempo all”interno di una richiesta? | Breakdown a livello nanosecondo |
| È stata una syscall, un blocco o calcolo? | La sequenza di chiamata lo mostra |
Options Worth Knowing
| Flag | Purpose |
|---|
-multi-thread | Traccia tutti i thread |
-duration | Lunghezza della finestra di cattura |
-trigger SYMBOL | Snapshot su un simbolo |
-full-execution | Traccia un”intera esecuzione breve |
-output FILE | Percorso di output della traccia |
Limitations
| Limitation | Note |
|---|
| Intel only | Richiede Intel PT (niente AMD/ARM) |
| Short window | Milliseconda, non minuti |
| Symbol quality | I binari spogliati producono tracce scarse |
| Overhead | Basso ma non zero durante il tracing |
| Aspect | magic-trace | perf | Perfetto |
|---|
| Data | Flusso di controllo completo (Intel PT) | Stack campionati | Timeline di sistema |
| Resolution | Nanosecondi | Intervallo di campione | Livello di evento |
| Window | Ultimi millisecondi | Intera esecuzione | Configurabile |
| Best for | Picchi di latenza rari | Percorsi hot medi | Correlazione di sistema |
Usa perf per i percorsi hot medi, Perfetto per le timeline di sistema e magic-trace quando hai bisogno della storia esatta di un evento lento raro.
Resources
