magic-trace - Traçage haute résolution Intel PT
magic-trace (par Jane Street) capture et affiche des traces d’exécution haute résolution en utilisant Intel Processor Trace (Intel PT). Alors qu’un profileur d’échantillonnage vous dit où va le temps en moyenne, magic-trace enregistre le flux de contrôle réel — chaque entrée et sortie de fonction — pour les dernières millisecondes, à une résolution nanosecondes. Cela le rend uniquement approprié pour les événements rares et sensibles à la latence : la requête unique sur dix mille qui a pris 40ms, où un profil moyenné vous montre rien.
Prérequis
- CPU Intel avec support Intel Processor Trace (la plupart des Intel modernes)
- Linux avec perf et PT activés
- Root ou paramètre
perf_event_paranoid approprié
- Binaires avec frame pointers / symboles pour une sortie lisible
Installation
| Méthode | Commande |
|---|
| Binaire | télécharger magic-trace depuis les GitHub Releases |
| opam (OCaml) | opam install magic_trace |
| Permissions | sysctl kernel.perf_event_paranoid=-1 (ou 1) |
| Vérifier | magic-trace --help |
Deux modes de capture
| Mode | Commande | Utiliser |
|---|
| Attacher au service en cours | magic-trace attach -pid <pid> | Service live |
| Exécuter une commande | magic-trace run ./my-program | Exécution reproductible |
# Attacher, capturer sur Ctrl-C, écrire une trace
sudo magic-trace attach -pid $(pgrep -n myservice)
Déclencheurs de snapshot
L’idée clé : maintenir un buffer circulaire et faire un snapshot quand quelque chose d’intéressant se produit.
| Déclencheur | Comment |
|---|
| Manuel | Appuyer sur Ctrl-C lors de l’attachement |
| Point d’arrêt magique | L’app appelle un symbole désigné pour déclencher un snapshot |
| Timer | Capturer après une durée fixe |
| Déclencheur de symbole | -trigger <symbol> pour faire un snapshot sur un appel de fonction |
# Faire un snapshot chaque fois qu'une fonction spécifique est frappée
sudo magic-trace attach -pid <pid> -trigger 'handle_slow_path'
Parce que le buffer contient les précédentes millisecondes, vous voyez ce qui a mené à l’événement, pas juste l’événement lui-même.
Visualisation des traces
magic-trace émet une trace visualisable dans l’UI Perfetto.
| Étape | Action |
|---|
| 1 | La capture produit trace.fxt (ou similaire) |
| 2 | Ouvrir ui.perfetto.dev |
| 3 | Charger le fichier de trace |
| 4 | Zoomer dans la gamme de microsecondes d’intérêt |
| 5 | Lire la séquence d’appels exacte et les durées |
| Contrôle Perfetto | Fait |
|---|
W/S | Zoomer in/out |
A/D | Déplacer |
| Cliquer sur une tranche | Détail de durée et de fonction |
| Sélectionner une gamme | Résumé de ce qui a tourné |
Ce que vous pouvez voir
| Question | Réponse magic-trace |
|---|
| Quelle fonction a causé ce pic de 40ms ? | Appel exact, durée exacte |
| Avons-nous pris une branche inattendue ? | Flux de contrôle complet, visible |
| Où le temps est allé dans une requête ? | Décomposition au niveau nanoseconde |
| Était-ce un syscall, un verrou, ou du calcul ? | La séquence d’appels le montre |
Options qui valent le coup
| Flag | Objectif |
|---|
-multi-thread | Tracer tous les threads |
-duration | Longueur de la fenêtre de capture |
-trigger SYMBOL | Snapshot sur un symbole |
-full-execution | Tracer une exécution courte complète |
-output FILE | Chemin de sortie de trace |
Limitations
| Limitation | Note |
|---|
| Intel uniquement | Nécessite Intel PT (pas AMD/ARM) |
| Fenêtre courte | Millisecondes, pas minutes |
| Qualité des symboles | Les binaires dépouillés donnent de mauvaises traces |
| Surcharge | Faible mais non-zéro lors du traçage |
magic-trace vs outils connexes
| Aspect | magic-trace | perf | Perfetto |
|---|
| Données | Flux de contrôle complet (Intel PT) | Piles échantillonnées | Chronologie système |
| Résolution | Nanosecondes | Intervalle d’échantillonnage | Au niveau des événements |
| Fenêtre | Derniers ms | Exécution entière | Configurable |
| Meilleur pour | Pics de latence rares | Chemins chauds moyens | Corrélations système |
Utiliser perf pour les chemins chauds moyens, Perfetto pour les chronologies système, et magic-trace quand vous avez besoin de l’histoire exacte d’un événement lent rare.
Ressources
