Skip to main content

​
resq-flame

Version: v0.1.16 · License: Apache-2.0 · Crate: crates.io · API docs: docs.rs
SVG CPU flame graph profiler for ResQ services

​
Overview

Crates.io License Interactive CPU profiler and SVG flame graph generator for ResQ services. Provides a TUI for selecting profiling targets and a subcommand interface for scripted profiling, piping output through inferno-flamegraph.

​
Overview

resq-flame supports multiple profiling backends (V8 CPU profiles, pprof, py-spy, Linux perf) and converts their output into the folded-stack format consumed by inferno. The result is an interactive SVG flame graph you can open in any browser.

​
Profiling Pipeline

​
Installation

# From the workspace root
cargo build --release -p resq-flame

# Binary location
target/release/resq-flame

​
Prerequisites

ToolRequired ForInstall
infernoAll SVG generationcargo install inferno
py-spyPython (PDIE) profilingpip install py-spy
perfLinux kernel profilingsudo apt install linux-perf or sudo pacman -S perf

​
CLI Arguments

​
Global Flags

FlagShortDefaultDescription
--output <path>-oflamegraph.svgOutput SVG file path
--openfalseOpen the SVG in the default browser after generation

​
Subcommand: hce

Fetch a V8 CPU profile from the Coordination HCE server.
FlagShortDefaultDescription
--url <url>-uhttp://localhost:5000HCE server URL
--duration <ms>-d5000Profile duration in milliseconds

​
Usage Examples

​
Interactive TUI (default)

# Launch the target selection TUI
resq-flame
Use arrow keys or j/k to navigate, Enter to start profiling the selected target, and q or Esc to quit.

​
Subcommand Mode

# Profile the HCE service for 5 seconds
resq-flame hce

# Profile with custom URL and duration, output to custom path
resq-flame hce --url http://staging:5000 --duration 10000 --output hce-profile.svg

# Profile and auto-open in browser
resq-flame --open hce --duration 3000

​
Profiling Targets (TUI)

TargetEngineDescription
Coordination HCEhceNode.js/Bun service via HTTP metrics
Infrastructure APIapiRust backend via pprof
Intelligence PDIEpythonPython AI engine via py-spy
Linux PerfperfSystem-wide profiling via perf record

​
TUI Keybindings

KeyAction
q / EscQuit
EnterProfile the selected target
Up / kMove selection up
Down / jMove selection down

​
Environment Variables

VariableDescription
RESQ_TOKENBearer token for HCE authentication
RESQ_API_KEYAPI key for infrastructure-api and PDIE

​
Output Format

The tool generates interactive SVG flame graphs using the inferno crate:
  • Folded stacks are the intermediate format (frame1;frame2;frameN count).
  • SVG output supports interactive features when opened in a browser: click to zoom, Ctrl+F to search.

​
Input Format Support

FormatFunctionDescription
V8 .cpuprofilecpuprofile_to_foldedChrome/Node.js CPU profiles with tree structure
bpftrace histogramparse_bpftrace_outputframe1, frame2: count lines
Pre-folded stacksparse_folded_stacksStandard stack count lines

​
Reading Flame Graphs

  • Width of a frame = proportion of total samples where that function was on the stack
  • Height = call depth (bottom is root, top is leaf)
  • Wide frames at the top = hot leaf functions (primary optimization targets)
  • Wide frames in the middle = called frequently from many paths

​
Safety Notes

  • Profiling is read-only — it does not modify the target service.
  • External profiler binaries (py-spy, perf) are invoked as subprocesses; the tool handles missing binaries gracefully.
  • Use reasonable durations when profiling production environments to minimize overhead.
  • The HCE subcommand connects via HTTP and does not require kernel-level access.
  • perf mode requires appropriate Linux capabilities (CAP_SYS_ADMIN or perf_event_paranoid settings).

​
Typical Workflow

# 1. Start the target service
cargo run --manifest-path services/infrastructure-api/Cargo.toml

# 2. Generate load
cd services/simulation-harness && dotnet run

# 3. Profile while load is running
resq-flame --output before.svg hce --duration 30000

# 4. Make optimizations, restart, re-profile
resq-flame --output after.svg hce --duration 30000

# 5. Compare the two flame graphs visually

​
License

Licensed under the Apache License, Version 2.0. See LICENSE for details.