resq-flame-0.1.15 is not a library.

resq-flame

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

flowchart LR
    A[Launch resq-flame] --> B{Mode?}
    B -->|Interactive| C[TUI: Select Target]
    B -->|Subcommand| D[CLI: resq-flame hce ...]

    C --> E[Dispatch Profiling Engine]
    D --> E

    E --> F{Engine}
    F -->|HCE| G[V8 CPU Profile via HTTP]
    F -->|API| H[Rust pprof]
    F -->|PDIE| I[py-spy]
    F -->|Perf| J[Linux perf record]

    G --> K[Parse to Folded Stacks]
    H --> K
    I --> K
    J --> K

    K --> L[inferno-flamegraph]
    L --> M[Output SVG]
    M --> N{--open flag?}
    N -->|Yes| O[Open in Browser]
    N -->|No| P[Done]

Installation

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

# Binary location
target/release/resq-flame

Prerequisites

Tool	Required For	Install
`inferno`	All SVG generation	`cargo install inferno`
`py-spy`	Python (PDIE) profiling	`pip install py-spy`
`perf`	Linux kernel profiling	`sudo apt install linux-perf` or `sudo pacman -S perf`

CLI Arguments

Global Flags

Flag	Short	Default	Description
`--output <path>`	`-o`	`flamegraph.svg`	Output SVG file path
`--open`		`false`	Open the SVG in the default browser after generation

Subcommand: `hce`

Fetch a V8 CPU profile from the Coordination HCE server.

Flag	Short	Default	Description
`--url <url>`	`-u`	`http://localhost:5000`	HCE server URL
`--duration <ms>`	`-d`	`5000`	Profile 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)

Target	Engine	Description
Coordination HCE	`hce`	Node.js/Bun service via HTTP metrics
Infrastructure API	`api`	Rust backend via pprof
Intelligence PDIE	`python`	Python AI engine via py-spy
Linux Perf	`perf`	System-wide profiling via `perf record`

TUI Keybindings

Key	Action
`q` / `Esc`	Quit
`Enter`	Profile the selected target
`Up` / `k`	Move selection up
`Down` / `j`	Move selection down

Environment Variables

Variable	Description
`RESQ_TOKEN`	Bearer token for HCE authentication
`RESQ_API_KEY`	API 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

Format	Function	Description
V8 `.cpuprofile`	`cpuprofile_to_folded`	Chrome/Node.js CPU profiles with tree structure
bpftrace histogram	`parse_bpftrace_output`	`frame1, frame2: count` lines
Pre-folded stacks	`parse_folded_stacks`	Standard `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.

resq-flame 0.1.15