Comandos de speedscope

speedscope es un visor rápido, interactivo y basado en web para perfiles de rendimiento. Soporta la importación de datos de muchos perfiladores y proporciona tres modos de visualización: orden temporal, peso izquierdo (flame graph tradicional) y vista sandwich para analizar funciones individuales.

Instalación

Linux/Ubuntu

# Install via npm (globally)
npm install -g speedscope

# Or use npx without installing
npx speedscope profile.json

# Verify installation
speedscope --version

# speedscope runs locally in your browser — no data is sent to any server

Basado en web (sin instalación)

# Abrir https://speedscope.app en tu navegador
# Arrastrar y soltar un archivo de perfil en la página
# O usar el selector de archivos para seleccionar un perfil

# Todo el procesamiento ocurre del lado del cliente en el navegador

Uso del CLI

# Abrir un perfil en el navegador predeterminado
speedscope profile.json

# Abrir un formato de archivo específico
speedscope perf.data.json
speedscope profile.pb.gz
speedscope chrome_trace.json

# Enviar datos directamente desde un perfilador
py-spy record --format speedscope -o - -- python app.py | speedscope -

# Abrir múltiples perfiles para comparación
speedscope before.json after.json

Formatos soportados

Formato	Herramienta de origen	Extensión de archivo
speedscope JSON	Formato nativo	`.speedscope.json`
pprof	Go pprof, py-spy	`.pb.gz`, `.pb`
Chrome Trace	Chrome DevTools, Node.js	`.json`
Firefox Profile	Firefox Profiler	`.json`
Brendan Gregg folded	FlameGraph stackcollapse	`.folded`, `.txt`
callgrind	Valgrind, cachegrind	`callgrind.out.*`
Instruments	Xcode Instruments	`.trace`
Linux perf	`perf script`	`.perf`, `.txt`
DTrace	Pilas colapsadas DTrace	`.txt`
Haskell prof	Perfilador GHC	`.prof`
Safari Timeline	Safari Web Inspector	`.json`

Generar perfiles para speedscope

Desde py-spy (Python)

# Generar salida compatible con speedscope
py-spy record --format speedscope -o profile.speedscope.json -- python my_script.py

# Desde un proceso en ejecución
sudo py-spy record --format speedscope -o profile.speedscope.json --pid 1234

Desde perf (Linux)

# Grabar con perf
perf record -F 99 -g -- ./my_program
perf script > out.perf

# Convertir a pilas plegadas (speedscope las lee)
stackcollapse-perf.pl out.perf > out.folded

# Abrir en speedscope
speedscope out.folded

Desde Go pprof

# Generar un perfil de CPU
go tool pprof -proto http://localhost:6060/debug/pprof/profile?seconds=30 > cpu.pb.gz

# Abrir en speedscope
speedscope cpu.pb.gz

# O generar desde un test Go
go test -cpuprofile cpu.pb.gz -bench .
speedscope cpu.pb.gz

Desde Chrome DevTools

# 1. Abrir Chrome DevTools > pestaña Performance
# 2. Hacer clic en Record, reproducir el problema, hacer clic en Stop
# 3. Hacer clic en la flecha hacia abajo (Exportar) para guardar como JSON
# 4. Abrir el archivo JSON en speedscope
speedscope chrome_profile.json

Desde Node.js

# Generar un perfil de CPU V8
node --cpu-prof --cpu-prof-dir=./profiles my_app.js

# Abrir el archivo .cpuprofile generado
speedscope profiles/*.cpuprofile

# Usando clinic.js flame
npx clinic flame -- node my_app.js
# La salida HTML contiene datos que pueden ser exportados

Desde Ruby (stackprof)

# Generar un perfil stackprof
# En código Ruby:
# StackProf.run(mode: :cpu, out: 'stackprof.dump') { do_work }

# Convertir a formato speedscope
stackprof --flamegraph stackprof.dump > flamegraph.json
speedscope flamegraph.json

Modos de vista

Vista de orden temporal

# Muestra eventos en orden cronológico (izquierda a derecha = tiempo)
# - El eje X representa el tiempo de reloj
# - El eje Y representa la profundidad de la pila de llamadas
# - Útil para entender el flujo de ejecución y temporización
# - Muestra cuándo se llamaron funciones específicas
# - Ayuda a identificar fases y patrones en la ejecución
# - Navegar: desplazar horizontalmente para moverse en el tiempo

Vista de peso izquierdo

# Flame graph tradicional (agregado por ruta de llamadas)
# - Los marcos de pila idénticos se fusionan y ordenan por peso
# - El eje X representa el tiempo total (más ancho = más tiempo)
# - El eje Y representa la profundidad de la pila de llamadas
# - Mejor para encontrar puntos calientes y objetivos de optimización
# - Similar a los flame graphs de Brendan Gregg
# - Navegar: clic para ampliar un subárbol

Vista sandwich

# Enfocarse en una sola función mostrando llamadores y llamados
# - Seleccionar cualquier función para ver su contexto completo
# - Sección superior: quién llamó a esta función (llamadores)
# - Sección inferior: qué llama esta función (llamados)
# - Centro: la función seleccionada
# - Excelente para entender el rol de una función específica
# - Navegar: clic en nombres de funciones para re-centrar

Atajos de teclado

Atajo	Acción
`1`	Cambiar a vista de orden temporal
`2`	Cambiar a vista de peso izquierdo
`3`	Cambiar a vista sandwich
`f` o `/`	Abrir búsqueda
`Enter`	Confirmar búsqueda
`Escape`	Cerrar búsqueda o restablecer zoom
`r`	Restablecer vista / zoom
`n`	Siguiente coincidencia de búsqueda
`Shift+n`	Coincidencia anterior de búsqueda
`+` / `=`	Ampliar
`-`	Reducir
`0`	Ajustar a la ventana
`h` / Flecha izquierda	Desplazar a la izquierda
`l` / Flecha derecha	Desplazar a la derecha
Rueda del ratón	Ampliar/reducir en el cursor

Formato JSON de speedscope

{
  "$schema": "https://www.speedscope.app/file-format-schema.json",
  "shared": {
    "frames": [
      {"name": "main", "file": "app.py", "line": 10},
      {"name": "process_data", "file": "app.py", "line": 25},
      {"name": "transform", "file": "utils.py", "line": 42}
    ]
  },
  "profiles": [
    {
      "type": "sampled",
      "name": "CPU Profile",
      "unit": "milliseconds",
      "startValue": 0,
      "endValue": 5000,
      "samples": [[0, 1, 2], [0, 1], [0, 1, 2]],
      "weights": [10, 10, 10]
    }
  ]
}

Consejos y flujos de trabajo

# Flujo de trabajo rápido de comparación A/B
# 1. Perfilar antes de la optimización
py-spy record --format speedscope -o before.json -- python my_script.py

# 2. Hacer cambios en el código, luego perfilar de nuevo
py-spy record --format speedscope -o after.json -- python my_script.py

# 3. Abrir ambos en pestañas de speedscope para comparación
speedscope before.json &
speedscope after.json &

# Conversión entre formatos
# Pilas plegadas a speedscope: solo abrir directamente
speedscope my_folded_stacks.txt

# Múltiples perfiles en un archivo
# El JSON de speedscope soporta múltiples perfiles en el array "profiles"
# Cada uno aparece como una pestaña separada en el visor

# Auto-alojamiento de speedscope
# Clonar y servir los archivos estáticos
git clone https://github.com/jlfwong/speedscope.git
cd speedscope && python3 -m http.server 8080
# Abrir http://localhost:8080

Referencia rápida

Característica	Descripción
Orden temporal	Vista de ejecución cronológica
Peso izquierdo	Vista de flame graph agregado
Sandwich	Vista enfocada en llamador/llamado
Búsqueda	Resaltar marcos coincidentes
Zoom	Clic en marcos o usar rueda de desplazamiento
Exportar	Guardar vista actual como PNG
Arrastrar y soltar	Cargar archivos soltándolos en la página
Privacidad	Todo el procesamiento es del lado del cliente