platformatic/flame

Utility to generate flamegraphs

JavaScript

176

179 commits

updated Sep 21, 2026

See the code

README

@platformatic/flame

🔥 CPU and heap profiling and flamegraph visualization tool built on top of @platformatic/react-pprof.

Features

Dual Profiling: Captures both CPU and heap profiles concurrently for comprehensive performance insights
Auto-Start Profiling: Profiling starts immediately when using flame run (default behavior)
Automatic Flamegraph Generation: Interactive HTML flamegraphs are created automatically for both CPU and heap profiles on exit
LLM-Friendly Markdown Analysis: Generates markdown reports with hotspot analysis, ideal for AI-assisted performance debugging
Sourcemap Support: Automatically translates transpiled code locations back to original source files (TypeScript, bundled JavaScript, etc.)
Clear File Path Display: Shows exact paths and browser URLs for generated files
Manual Control: Optional manual mode with signal-based control using SIGUSR2
Interactive Visualization: WebGL-based HTML flamegraphs with zoom, search, and filtering
CLI Interface: Simple command-line tool for profiling and visualization
Zero Config: Works out of the box with sensible defaults

Installation

npm install -g @platformatic/flame

Quick Start

Profile a Node.js Script (Auto-Start Mode)

# Start profiling your application (profiling begins immediately)
flame run server.js

# The application runs with CPU and heap profiling active
# When you stop the app (Ctrl-C or normal exit), you'll see:
# 🔥 CPU profile written to: cpu-profile-2025-08-27T12-00-00-000Z.pb
# 🔥 Heap profile written to: heap-profile-2025-08-27T12-00-00-000Z.pb
# 🔥 Generating CPU flamegraph...
# 🔥 CPU flamegraph generated: cpu-profile-2025-08-27T12-00-00-000Z.html
# 🔥 CPU markdown generated: cpu-profile-2025-08-27T12-00-00-000Z.md
# 🔥 Generating heap flamegraph...
# 🔥 Heap flamegraph generated: heap-profile-2025-08-27T12-00-00-000Z.html
# 🔥 Heap markdown generated: heap-profile-2025-08-27T12-00-00-000Z.md
# 🔥 Open file:///path/to/cpu-profile-2025-08-27T12-00-00-000Z.html in your browser to view the CPU flamegraph

Manual Profiling Mode

# Start profiling in manual mode (requires signals to start)
flame run --manual server.js

# In another terminal, toggle profiling on/off
kill -USR2 <PID>

# Or use the built-in toggle command
flame toggle

Generate Flamegraph and Markdown

# Generate HTML flamegraph and markdown from pprof file
flame generate cpu-profile-2024-01-01T12-00-00-000Z.pb

# Specify custom output file
flame generate -o my-flamegraph.html profile.pb.gz

# Use detailed markdown format for comprehensive analysis
flame generate --md-format=detailed profile.pb

CLI Usage

flame [options] <command>

Commands:
  run <script>           Run a script with profiling enabled
  generate <pprof-file>  Generate HTML flamegraph and markdown from pprof file
  toggle                 Toggle profiling for running flame processes

Options:
  -o, --output <file>       Output HTML file (for generate command)
  -m, --manual             Manual profiling mode (require SIGUSR2 to start)
  -d, --delay <value>      Delay before starting profiler (ms, 'none', or 'until-started')
  -s, --sourcemap-dirs <dirs>  Directories to search for sourcemaps (colon/semicolon-separated)
      --md-format <format>  Markdown format: summary (default), detailed, or adaptive
      --node-options <options>  Node.js CLI options to pass to the profiled process
  -h, --help               Show help message
  -v, --version            Show version number

Programmatic API

const { startProfiling, generateFlamegraph, generateMarkdown, parseProfile } = require('@platformatic/flame')

// Start profiling a script with auto-start (default)
const { pid, toggleProfiler } = startProfiling('server.js', ['--port', '3000'], { autoStart: true })

// Or start in manual mode
const { pid, toggleProfiler } = startProfiling('server.js', ['--port', '3000'], { autoStart: false })

console.log(`Started profiling process ${pid}`)

// Toggle profiling programmatically (useful in manual mode)
toggleProfiler()

// Generate interactive flamegraph from pprof file
await generateFlamegraph('profile.pb.gz', 'flamegraph.html')

// Generate LLM-friendly markdown analysis
await generateMarkdown('profile.pb', 'analysis.md', { format: 'summary' })

// Parse profile data
const profile = await parseProfile('profile.pb')

How It Works

Auto-Start Mode (Default): Both CPU and heap profiling begin immediately when flame run starts your script
Auto-Generation on Exit: Profile (.pb) files, interactive HTML flamegraphs, and markdown analysis files are automatically created for both CPU and heap profiles when the process exits
Manual Mode: Use --manual flag to require SIGUSR2 signals for start/stop control (no auto-HTML generation)
Interactive Visualization: The @platformatic/react-pprof library generates interactive WebGL-based HTML flamegraphs for both profile types
Markdown Analysis: The pprof-to-md library generates LLM-friendly markdown reports with hotspot tables for AI-assisted debugging

Sourcemap Support

When profiling transpiled or bundled applications (TypeScript, Webpack, ESBuild, etc.), the flame tool can automatically translate stack traces from generated code back to your original source files using sourcemaps.

Usage

# Profile a TypeScript application with sourcemap support
flame run --sourcemap-dirs=dist server.js

# Search multiple directories (colon or semicolon separated)
flame run --sourcemap-dirs=dist:build:out server.js

How It Works

The tool searches specified directories for .map, .js.map, .cjs.map, and .mjs.map files
During profiling, stack frame locations are automatically translated from generated code to source locations
The resulting flamegraph shows your original source file paths and line numbers

Programmatic API

const { startProfiling } = require('@platformatic/flame')

startProfiling('dist/server.js', [], {
  autoStart: true,
  sourcemapDirs: ['dist', 'build']  // Can be a string or array
})

Environment Variables

Sourcemap support can also be controlled via environment variables:

# Specify directories (colon/semicolon separated)
export FLAME_SOURCEMAP_DIRS="dist:build"

# Then run normally
flame run server.js

Notes

Sourcemaps are loaded at startup and applied during profile capture
The tool excludes node_modules directories when searching
If a sourcemap cannot be found or fails to parse, the original generated location is preserved
Both CPU and heap profiles benefit from sourcemap translation

Profile Files

Profile files are saved with timestamps in the format:

cpu-profile-2024-01-01T12-00-00-000Z.pb     # Binary pprof data
cpu-profile-2024-01-01T12-00-00-000Z.html   # Interactive flamegraph
cpu-profile-2024-01-01T12-00-00-000Z.md     # LLM-friendly markdown analysis
heap-profile-2024-01-01T12-00-00-000Z.pb
heap-profile-2024-01-01T12-00-00-000Z.html
heap-profile-2024-01-01T12-00-00-000Z.md

Both CPU and heap profiles share the same timestamp for easy correlation. The .pb files are compressed Protocol Buffer format compatible with the pprof ecosystem. The .md files contain hotspot analysis tables suitable for AI/LLM-assisted performance debugging.

Markdown Formats

The --md-format option controls the markdown output:

summary (default): Compact hotspots table, ideal for AI triage and quick overview
detailed: Comprehensive analysis with full stack traces and detailed statistics
adaptive: Automatically chooses format based on profile complexity

Integration with Existing Apps

Express.js Example

// server.js
const express = require('express')
const app = express()

app.get('/', (req, res) => {
  // Your application logic
  res.json({ message: 'Hello World' })
})

app.listen(3000)

Auto-Start Mode (Recommended):

# Profile the Express app (profiling starts immediately)
flame run server.js

# In another terminal, make some requests while profiling is active
curl http://localhost:3000
curl http://localhost:3000
curl http://localhost:3000

# Stop the server (Ctrl-C) to automatically save profiles and generate flamegraphs
# You'll see the exact file paths and browser URLs in the output:
# 🔥 CPU profile written to: cpu-profile-2025-08-27T15-30-45-123Z.pb
# 🔥 Heap profile written to: heap-profile-2025-08-27T15-30-45-123Z.pb
# 🔥 CPU flamegraph generated: cpu-profile-2025-08-27T15-30-45-123Z.html
# 🔥 CPU markdown generated: cpu-profile-2025-08-27T15-30-45-123Z.md
# 🔥 Heap flamegraph generated: heap-profile-2025-08-27T15-30-45-123Z.html
# 🔥 Heap markdown generated: heap-profile-2025-08-27T15-30-45-123Z.md
# 🔥 Open file:///path/to/cpu-profile-2025-08-27T15-30-45-123Z.html in your browser to view the CPU flamegraph

Manual Mode:

# Profile the Express app in manual mode
flame run --manual server.js

# In another terminal, start profiling
flame toggle

# Make some requests
curl http://localhost:3000
curl http://localhost:3000

# Stop profiling and save profile
flame toggle

# Generate flamegraph
flame generate cpu-profile-*.pb

Example Applications

Two comprehensive benchmark applications are included for testing profiling overhead and feature Express.js middlewares and Fastify plugins with realistic computation endpoints.

Running Benchmark Apps

# Run individual apps without profiling
node examples/express-benchmark-app.js
node examples/fastify-benchmark-app.js

# Run comprehensive performance overhead analysis
node examples/run-performance-benchmark.js

Both apps include:

Health check endpoint (no computation)
Light computation endpoint (~1k iterations)
Medium computation endpoint (~10k iterations)
Heavy computation endpoint (~100k iterations)
Multiple middleware layers for realistic overhead testing
Comprehensive test suites

Performance Overhead Results

Based on comprehensive benchmarks with 10 concurrent connections over 10 seconds per endpoint:

Express.js Framework:

Endpoint	Load Level	Without Profiling	With Profiling	Throughput Overhead	Latency Overhead
Health Check	Minimal	13,571 req/s	13,752 req/s	-1.3%	-6.3%
Light Computation	Low	10,187 req/s	9,979 req/s	+2.0%	+12.0%
Medium Computation	Moderate	71 req/s	66 req/s	+6.1%	+6.3%
Heavy Computation	High	295 req/s	291 req/s	+1.3%	+1.4%
Mixed Computation	Very High	56 req/s	53 req/s	+5.2%	+5.8%

Express Summary: Average throughput overhead of 2.7% and latency overhead of 3.9%

Fastify Framework:

Endpoint	Load Level	Without Profiling	With Profiling	Throughput Overhead	Latency Overhead
Health Check	Minimal	41,174 req/s	38,747 req/s	+5.9%	0.0%
Light Computation	Low	35,056 req/s	32,847 req/s	+6.3%	0.0%
Medium Computation	Moderate	3,235 req/s	3,126 req/s	+3.4%	+4.2%
Heavy Computation	High	345 req/s	336 req/s	+2.6%	+2.6%
Mixed Computation	Very High	311 req/s	304 req/s	+2.3%	+2.3%

Fastify Summary: Average throughput overhead of 4.1% and latency overhead of 1.8%

CSV data is automatically generated when running node examples/run-performance-benchmark.js for further analysis.

Load Testing Example

You can run load tests manually:

# Terminal 1: Start the test server with profiling
flame run examples/load-test-server.js

# Terminal 2: Run load test with autocannon
npx autocannon -c 10 -d 10 http://localhost:3000

# Terminal 1: Toggle profiling (start/stop)
kill -USR2 <PID>

Requirements

Node.js >= 22.6.0
@datadog/pprof for CPU and heap profiling
react-pprof for flamegraph generation
pprof-to-md for markdown analysis generation

License

MIT

Contributors

97 commits

73 commits

7 commits

1 commits

Similar repos

davidmarkclements/0x

🔥 single-command flamegraph profiling 🔥

3,550

mourner/flamebearer

A JavaScript CPU trace analysis tool for agents and humans

1,661

mapbox/flamebearer

A JavaScript CPU trace analysis tool for agents and humans

1,661

clinicjs/node-clinic

Clinic.js diagnoses your Node.js performance issues

5,954

google/pprof-nodejs

pprof support for Node.js

291

flamegraph-rs/flamegraph

Easy flamegraphs for Rust projects and everything else, without Perl or pipes <3

6,032

zz85/profile-bee

🐝🦀🔥 Rust-based eBPF CPU profiler, supports stack unwinding

aws/aperf

An all-in-one CLI tool for performance monitoring, analysis, and debugging.

223

Languages

JavaScript

100.0%

platformatic/flame

Utility to generate flamegraphs

JavaScript

176

179 commits

updated Sep 21, 2026

See the code

README

@platformatic/flame

🔥 CPU and heap profiling and flamegraph visualization tool built on top of @platformatic/react-pprof.

Features

Dual Profiling: Captures both CPU and heap profiles concurrently for comprehensive performance insights
Auto-Start Profiling: Profiling starts immediately when using flame run (default behavior)
Automatic Flamegraph Generation: Interactive HTML flamegraphs are created automatically for both CPU and heap profiles on exit
LLM-Friendly Markdown Analysis: Generates markdown reports with hotspot analysis, ideal for AI-assisted performance debugging
Sourcemap Support: Automatically translates transpiled code locations back to original source files (TypeScript, bundled JavaScript, etc.)
Clear File Path Display: Shows exact paths and browser URLs for generated files
Manual Control: Optional manual mode with signal-based control using SIGUSR2
Interactive Visualization: WebGL-based HTML flamegraphs with zoom, search, and filtering
CLI Interface: Simple command-line tool for profiling and visualization
Zero Config: Works out of the box with sensible defaults

Installation

npm install -g @platformatic/flame

Quick Start

Profile a Node.js Script (Auto-Start Mode)

# Start profiling your application (profiling begins immediately)
flame run server.js

# The application runs with CPU and heap profiling active
# When you stop the app (Ctrl-C or normal exit), you'll see:
# 🔥 CPU profile written to: cpu-profile-2025-08-27T12-00-00-000Z.pb
# 🔥 Heap profile written to: heap-profile-2025-08-27T12-00-00-000Z.pb
# 🔥 Generating CPU flamegraph...
# 🔥 CPU flamegraph generated: cpu-profile-2025-08-27T12-00-00-000Z.html
# 🔥 CPU markdown generated: cpu-profile-2025-08-27T12-00-00-000Z.md
# 🔥 Generating heap flamegraph...
# 🔥 Heap flamegraph generated: heap-profile-2025-08-27T12-00-00-000Z.html
# 🔥 Heap markdown generated: heap-profile-2025-08-27T12-00-00-000Z.md
# 🔥 Open file:///path/to/cpu-profile-2025-08-27T12-00-00-000Z.html in your browser to view the CPU flamegraph

Manual Profiling Mode

# Start profiling in manual mode (requires signals to start)
flame run --manual server.js

# In another terminal, toggle profiling on/off
kill -USR2 <PID>

# Or use the built-in toggle command
flame toggle

Generate Flamegraph and Markdown

# Generate HTML flamegraph and markdown from pprof file
flame generate cpu-profile-2024-01-01T12-00-00-000Z.pb

# Specify custom output file
flame generate -o my-flamegraph.html profile.pb.gz

# Use detailed markdown format for comprehensive analysis
flame generate --md-format=detailed profile.pb

CLI Usage

flame [options] <command>

Commands:
  run <script>           Run a script with profiling enabled
  generate <pprof-file>  Generate HTML flamegraph and markdown from pprof file
  toggle                 Toggle profiling for running flame processes

Options:
  -o, --output <file>       Output HTML file (for generate command)
  -m, --manual             Manual profiling mode (require SIGUSR2 to start)
  -d, --delay <value>      Delay before starting profiler (ms, 'none', or 'until-started')
  -s, --sourcemap-dirs <dirs>  Directories to search for sourcemaps (colon/semicolon-separated)
      --md-format <format>  Markdown format: summary (default), detailed, or adaptive
      --node-options <options>  Node.js CLI options to pass to the profiled process
  -h, --help               Show help message
  -v, --version            Show version number

Programmatic API

const { startProfiling, generateFlamegraph, generateMarkdown, parseProfile } = require('@platformatic/flame')

// Start profiling a script with auto-start (default)
const { pid, toggleProfiler } = startProfiling('server.js', ['--port', '3000'], { autoStart: true })

// Or start in manual mode
const { pid, toggleProfiler } = startProfiling('server.js', ['--port', '3000'], { autoStart: false })

console.log(`Started profiling process ${pid}`)

// Toggle profiling programmatically (useful in manual mode)
toggleProfiler()

// Generate interactive flamegraph from pprof file
await generateFlamegraph('profile.pb.gz', 'flamegraph.html')

// Generate LLM-friendly markdown analysis
await generateMarkdown('profile.pb', 'analysis.md', { format: 'summary' })

// Parse profile data
const profile = await parseProfile('profile.pb')

How It Works

Auto-Start Mode (Default): Both CPU and heap profiling begin immediately when flame run starts your script
Auto-Generation on Exit: Profile (.pb) files, interactive HTML flamegraphs, and markdown analysis files are automatically created for both CPU and heap profiles when the process exits
Manual Mode: Use --manual flag to require SIGUSR2 signals for start/stop control (no auto-HTML generation)
Interactive Visualization: The @platformatic/react-pprof library generates interactive WebGL-based HTML flamegraphs for both profile types
Markdown Analysis: The pprof-to-md library generates LLM-friendly markdown reports with hotspot tables for AI-assisted debugging

Sourcemap Support

Usage

# Profile a TypeScript application with sourcemap support
flame run --sourcemap-dirs=dist server.js

# Search multiple directories (colon or semicolon separated)
flame run --sourcemap-dirs=dist:build:out server.js

How It Works

The tool searches specified directories for .map, .js.map, .cjs.map, and .mjs.map files
During profiling, stack frame locations are automatically translated from generated code to source locations
The resulting flamegraph shows your original source file paths and line numbers

Programmatic API

const { startProfiling } = require('@platformatic/flame')

startProfiling('dist/server.js', [], {
  autoStart: true,
  sourcemapDirs: ['dist', 'build']  // Can be a string or array
})

Environment Variables

Sourcemap support can also be controlled via environment variables:

# Specify directories (colon/semicolon separated)
export FLAME_SOURCEMAP_DIRS="dist:build"

# Then run normally
flame run server.js

Notes

Sourcemaps are loaded at startup and applied during profile capture
The tool excludes node_modules directories when searching
If a sourcemap cannot be found or fails to parse, the original generated location is preserved
Both CPU and heap profiles benefit from sourcemap translation

Profile Files

Profile files are saved with timestamps in the format:

cpu-profile-2024-01-01T12-00-00-000Z.pb     # Binary pprof data
cpu-profile-2024-01-01T12-00-00-000Z.html   # Interactive flamegraph
cpu-profile-2024-01-01T12-00-00-000Z.md     # LLM-friendly markdown analysis
heap-profile-2024-01-01T12-00-00-000Z.pb
heap-profile-2024-01-01T12-00-00-000Z.html
heap-profile-2024-01-01T12-00-00-000Z.md

Markdown Formats

The --md-format option controls the markdown output:

summary (default): Compact hotspots table, ideal for AI triage and quick overview
detailed: Comprehensive analysis with full stack traces and detailed statistics
adaptive: Automatically chooses format based on profile complexity

Integration with Existing Apps

Express.js Example

// server.js
const express = require('express')
const app = express()

app.get('/', (req, res) => {
  // Your application logic
  res.json({ message: 'Hello World' })
})

app.listen(3000)

Auto-Start Mode (Recommended):

# Profile the Express app (profiling starts immediately)
flame run server.js

# In another terminal, make some requests while profiling is active
curl http://localhost:3000
curl http://localhost:3000
curl http://localhost:3000

# Stop the server (Ctrl-C) to automatically save profiles and generate flamegraphs
# You'll see the exact file paths and browser URLs in the output:
# 🔥 CPU profile written to: cpu-profile-2025-08-27T15-30-45-123Z.pb
# 🔥 Heap profile written to: heap-profile-2025-08-27T15-30-45-123Z.pb
# 🔥 CPU flamegraph generated: cpu-profile-2025-08-27T15-30-45-123Z.html
# 🔥 CPU markdown generated: cpu-profile-2025-08-27T15-30-45-123Z.md
# 🔥 Heap flamegraph generated: heap-profile-2025-08-27T15-30-45-123Z.html
# 🔥 Heap markdown generated: heap-profile-2025-08-27T15-30-45-123Z.md
# 🔥 Open file:///path/to/cpu-profile-2025-08-27T15-30-45-123Z.html in your browser to view the CPU flamegraph

Manual Mode:

# Profile the Express app in manual mode
flame run --manual server.js

# In another terminal, start profiling
flame toggle

# Make some requests
curl http://localhost:3000
curl http://localhost:3000

# Stop profiling and save profile
flame toggle

# Generate flamegraph
flame generate cpu-profile-*.pb

Example Applications

Two comprehensive benchmark applications are included for testing profiling overhead and feature Express.js middlewares and Fastify plugins with realistic computation endpoints.

Running Benchmark Apps

# Run individual apps without profiling
node examples/express-benchmark-app.js
node examples/fastify-benchmark-app.js

# Run comprehensive performance overhead analysis
node examples/run-performance-benchmark.js

Both apps include:

Health check endpoint (no computation)
Light computation endpoint (~1k iterations)
Medium computation endpoint (~10k iterations)
Heavy computation endpoint (~100k iterations)
Multiple middleware layers for realistic overhead testing
Comprehensive test suites

Performance Overhead Results

Based on comprehensive benchmarks with 10 concurrent connections over 10 seconds per endpoint:

Express.js Framework:

Endpoint	Load Level	Without Profiling	With Profiling	Throughput Overhead	Latency Overhead
Health Check	Minimal	13,571 req/s	13,752 req/s	-1.3%	-6.3%
Light Computation	Low	10,187 req/s	9,979 req/s	+2.0%	+12.0%
Medium Computation	Moderate	71 req/s	66 req/s	+6.1%	+6.3%
Heavy Computation	High	295 req/s	291 req/s	+1.3%	+1.4%
Mixed Computation	Very High	56 req/s	53 req/s	+5.2%	+5.8%

Express Summary: Average throughput overhead of 2.7% and latency overhead of 3.9%

Fastify Framework:

Endpoint	Load Level	Without Profiling	With Profiling	Throughput Overhead	Latency Overhead
Health Check	Minimal	41,174 req/s	38,747 req/s	+5.9%	0.0%
Light Computation	Low	35,056 req/s	32,847 req/s	+6.3%	0.0%
Medium Computation	Moderate	3,235 req/s	3,126 req/s	+3.4%	+4.2%
Heavy Computation	High	345 req/s	336 req/s	+2.6%	+2.6%
Mixed Computation	Very High	311 req/s	304 req/s	+2.3%	+2.3%

Fastify Summary: Average throughput overhead of 4.1% and latency overhead of 1.8%

CSV data is automatically generated when running node examples/run-performance-benchmark.js for further analysis.

Load Testing Example

You can run load tests manually:

# Terminal 1: Start the test server with profiling
flame run examples/load-test-server.js

# Terminal 2: Run load test with autocannon
npx autocannon -c 10 -d 10 http://localhost:3000

# Terminal 1: Toggle profiling (start/stop)
kill -USR2 <PID>

Requirements

Node.js >= 22.6.0
@datadog/pprof for CPU and heap profiling
react-pprof for flamegraph generation
pprof-to-md for markdown analysis generation

License

MIT

Similar repos

davidmarkclements/0x

🔥 single-command flamegraph profiling 🔥

3,550

mourner/flamebearer

A JavaScript CPU trace analysis tool for agents and humans

1,661

mapbox/flamebearer

A JavaScript CPU trace analysis tool for agents and humans

1,661

clinicjs/node-clinic

Clinic.js diagnoses your Node.js performance issues

5,954

google/pprof-nodejs

pprof support for Node.js

291

flamegraph-rs/flamegraph

Easy flamegraphs for Rust projects and everything else, without Perl or pipes <3

6,032

zz85/profile-bee

🐝🦀🔥 Rust-based eBPF CPU profiler, supports stack unwinding

aws/aperf

An all-in-one CLI tool for performance monitoring, analysis, and debugging.

223

Contributors

97 commits

73 commits

7 commits

1 commits

Languages

JavaScript

100.0%