magic-trace - Rastreo de Alta Resolución de Intel PT Hoja de Trucos
magic-trace (de Jane Street) captura y muestra trazas de ejecución de alta resolución usando Intel Processor Trace (Intel PT). Donde un perfilador de muestreo te dice dónde va el tiempo en promedio, magic-trace graba el flujo de control actual — cada entrada y salida de función — durante los últimos pocos milisegundos, con resolución de nanosegundos. Eso lo hace únicamente adecuado para eventos raros y sensibles a la latencia: la una solicitud en diez mil que tomó 40ms, donde un perfil promediado no te muestra nada.
Requerimientos
- CPU Intel con soporte de Processor Trace (la mayoría de Intel moderno)
- Linux con perf y PT habilitado
- Root o configuración
perf_event_paranoid apropiada
- Binarios con frame pointers / símbolos para salida legible
Instalación
| Método | Comando |
|---|
| Binary | descargar magic-trace desde GitHub Releases |
| opam (OCaml) | opam install magic_trace |
| Permisos | sysctl kernel.perf_event_paranoid=-1 (o 1) |
| Verificar | magic-trace --help |
Dos Modos de Captura
| Modo | Comando | Uso |
|---|
| Adjuntar a ejecutándose | magic-trace attach -pid <pid> | Servicio vivo |
| Ejecutar un comando | magic-trace run ./my-program | Ejecución reproducible |
# Adjuntar, capturar en Ctrl-C, escribir un rastreo
sudo magic-trace attach -pid $(pgrep -n myservice)
Triggers de Snapshot
La idea principal: mantener un búfer rodante y snapshot cuando algo interesante sucede.
| Trigger | Cómo |
|---|
| Manual | Presionar Ctrl-C mientras está adjunto |
| Magic breakpoint | La app llamar un símbolo designado para activar un snapshot |
| Timer | Capturar después de duración fija |
| Trigger de símbolo | -trigger <symbol> para snapshot en llamada de función |
# Snapshot cada vez que una función específica es golpeada
sudo magic-trace attach -pid <pid> -trigger 'handle_slow_path'
Porque el búfer sostiene los precedentes pocos milisegundos, ves qué condujo al evento, no solo el evento en sí.
Visualizar Trazas
magic-trace emite un rastreo visualizable en la UI de Perfetto.
| Paso | Acción |
|---|
| 1 | Captura produce trace.fxt (o similar) |
| 2 | Abrir ui.perfetto.dev |
| 3 | Cargar el archivo de rastreo |
| 4 | Zoom en el rango de microsegundos de interés |
| 5 | Leer la secuencia de llamada exacta y duraciones |
| Control de Perfetto | Hace |
|---|
W/S | Zoom dentro/fuera |
A/D | Pan |
| Click en un slice | Detalle de duración y función |
| Seleccionar un rango | Resumen de lo que ejecutó |
Lo Que Puedes Ver
| Pregunta | Respuesta de magic-trace |
|---|
| ¿Qué función causó este spike de 40ms? | Llamada exacta, duración exacta |
| ¿Tomamos una rama inesperada? | Flujo de control completo, visible |
| ¿A dónde fue el tiempo dentro de una solicitud? | Desglose a nivel de nanosegundo |
| ¿Era un syscall, un bloqueo o cálculo? | La secuencia de llamada lo muestra |
Opciones Que Vale la Pena Conocer
| Flag | Propósito |
|---|
-multi-thread | Rastrear todos los threads |
-duration | Longitud de ventana de captura |
-trigger SYMBOL | Snapshot en un símbolo |
-full-execution | Rastrear una ejecución corta completa |
-output FILE | Ruta de salida de rastreo |
Limitaciones
| Limitación | Nota |
|---|
| Solo Intel | Requiere Intel PT (sin AMD/ARM) |
| Ventana corta | Milisegundos, no minutos |
| Calidad de símbolo | Binarios despojados dan trazas pobres |
| Overhead | Bajo pero no cero mientras rastrea |
magic-trace vs Herramientas Relacionadas
| Aspecto | magic-trace | perf | Perfetto |
|---|
| Datos | Flujo de control completo (Intel PT) | Stacks muestreados | Timeline de sistema |
| Resolución | Nanosegundos | Intervalo de muestra | Nivel de evento |
| Ventana | Últimos pocos ms | Ejecución completa | Configurable |
| Mejor para | Spikes raros de latencia | Caminos calientes promedio | Timelines de sistema |
Usa perf para caminos calientes promedio, Perfetto para timelines de sistema completo, y magic-trace cuando necesitas la historia exacta de un evento lento raro.
Recursos
