> ## Documentation Index
> Fetch the complete documentation index at: https://resq-dependabot-github-actions-github-actions-478e18be3d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Resq flame

# resq-flame

> **Version:** `v0.1.16` · **License:** `Apache-2.0` · **Crate:** [crates.io](https://crates.io/crates/resq-flame) · **API docs:** [docs.rs](https://docs.rs/resq-flame/0.1.16)

SVG CPU flame graph profiler for ResQ services

## Overview

[![Crates.io](https://img.shields.io/crates/v/resq-flame.svg)](https://crates.io/crates/resq-flame)
[![License](https://img.shields.io/crates/l/resq-flame.svg)](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

```mermaid theme={null}
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

```bash theme={null}
# 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)

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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](https://github.com/resq-software/crates/blob/master/LICENSE) for details.