magic-trace - Intel PT High-Resolution Tracing Cheatsheet
magic-trace (by Jane Street) erfasst und zeigt High-Resolution Execution Traces, die Intel Processor Trace (Intel PT) verwenden. Während ein Sampling Profiler dir sagt, wo die Zeit im Durchschnitt geht, zeichnet magic-trace den Tatsächlichen Kontrollflusss auf — jeder Funktionseintritt und -ausstieg — für die Letzte-Millisekunden mit Nanosekunden-Auflösung. Das macht es einzigartig geeignet für Seltene, Latency-Sensible Events: die eine Request in Zehntausend, die 40ms dauerte, wo ein Durchschnitt Profil dir nichts zeigt.
Anforderungen
- Intel CPU mit Processor Trace Support (meiste moderne Intel)
- Linux mit Perf und PT aktiviert
- Root oder angemessene
perf_event_paranoid Setting
- Binaries mit Frame Pointers / Symbols für lesbare Ausgabe
Installation
| Methode | Befehl |
|---|
| Binary | Download magic-trace von GitHub Releases |
| Opam (OCaml) | opam install magic_trace |
| Permissions | sysctl kernel.perf_event_paranoid=-1 (oder 1) |
| Verifikation | magic-trace --help |
Zwei Capture-Modi
| Mode | Befehl | Nutze |
|---|
| Attach zu Running | magic-trace attach -pid <pid> | Live Service |
| Run ein Befehl | magic-trace run ./my-program | Reproducible Run |
# Attach, Capture bei Ctrl-C, Write ein Trace
sudo magic-trace attach -pid $(pgrep -n myservice)
Snapshot Triggers
Die Core Idee: halte einen Rolling Buffer und Snapshot wenn etwas Interessantes passiert.
| Trigger | Wie |
|---|
| Manual | Press Ctrl-C während Attached |
| Magic Breakpoint | App ruft ein Designiertes Symbol auf um ein Snapshot zu triggern |
| Timer | Capture nach einer Fixed Duration |
| Symbol Trigger | -trigger <symbol> zu Snapshot auf einem Function Call |
# Snapshot wenn ein Spezifisches Function gehittet ist
sudo magic-trace attach -pid <pid> -trigger 'handle_slow_path'
Weil der Buffer die Vorangegangene Millisekunden hält, siehst du, was zum Event führte, nicht nur das Event selbst.
Viewing Traces
Magic-Trace emittiert ein Trace, das in der Perfetto UI sichtbar ist.
| Schritt | Action |
|---|
| 1 | Capture produziert trace.fxt (oder ähnlich) |
| 2 | Öffne ui.perfetto.dev |
| 3 | Load die Trace-Datei |
| 4 | Zoom in die Microsecond Range des Interesses |
| 5 | Lies die Exakte Call Sequence und Durations |
| Perfetto Control | Tut |
|---|
W/S | Zoom In/Out |
A/D | Pan |
| Click ein Slice | Duration und Function Detail |
| Select eine Range | Summary von was liefen war |
Was du sehen kannst
| Frage | magic-trace Antwort |
|---|
| Welche Function führte zu diesem 40ms Spike? | Exact Call, Exact Duration |
| Haben wir eine Unerwartete Branch genommen? | Full Control Flow, Sichtbar |
| Wo ging die Zeit innerhalb ein Request? | Nanosekund-Level Breakdown |
| War es ein Syscall, ein Lock oder Compute? | Die Call Sequence zeigt’s |
Options Werth Wissen
| Flag | Zweck |
|---|
-multi-thread | Trace alle Threads |
-duration | Länge von Capture Window |
-trigger SYMBOL | Snapshot auf einem Symbol |
-full-execution | Trace ein Ganzer Short Run |
-output FILE | Trace Output Path |
Limitations
| Limitation | Notiz |
|---|
| Intel only | Requires Intel PT (no AMD/ARM) |
| Short Window | Millisekunden, nicht Minuten |
| Symbol Quality | Stripped Binaries geben Schlechte Traces |
| Overhead | Niedrig aber Non-Zero während Tracing |
| Aspekt | magic-trace | perf | Perfetto |
|---|
| Data | Full Control Flow (Intel PT) | Sampled Stacks | System-Wide Timeline |
| Resolution | Nanosekunden | Sample Interval | Event-Level |
| Window | Letzter Few ms | Ganzer Run | Configurable |
| Am besten für | Seltene Latency Spikes | Average Hot Paths | System-Wide Correlation |
Nutze perf für Average Hot Paths, Perfetto für System-Wide Timelines und magic-trace wenn du die Exakte Story eines Rare Slow Events brauchst.
Ressourcen
