For programmatic generation of embeddable flamegraphs (e.g., for middleware or dynamic HTML generation), use the embedding API that supports rendering multiple graphs efficiently:
import { generateEmbeddableFlameGraph, getFlamegraphBundle } from 'react-pprof'import fs from 'fs'// Get the bundle once (it's cached internally)const { bundle } = await getFlamegraphBundle()// Generate embeddable flamegraphs for multiple profilesconst cpuProfile = fs.readFileSync('cpu-profile.pb')const heapProfile = fs.readFileSync('heap-profile.pb')const cpuGraph = await generateEmbeddableFlameGraph(cpuProfile, { title: 'CPU Profile', filename: 'cpu-profile.pb', primaryColor: '#ff4444', secondaryColor: '#ffcc66', height: 500})const heapGraph = await generateEmbeddableFlameGraph(heapProfile, { title: 'Heap Profile', filename: 'heap-profile.pb', primaryColor: '#ff4444', secondaryColor: '#ffcc66', height: 500})// Use in your HTML responseconst fullPage = `<!DOCTYPE html><html><head><title>Profiles</title></head><body> <h2>CPU Profile</h2> ${cpuGraph.html} <h2>Heap Profile</h2> ${heapGraph.html} <!-- Include bundle once --> <script>${bundle}</script> <!-- Render each graph --> <script>${cpuGraph.script}</script> <script>${heapGraph.script}</script></body></html>`
API
getFlamegraphBundle()
Returns the reusable React-pprof bundle code (cached after first call). Include this once in your page before rendering any graphs.
Generates embeddable HTML and JavaScript for a single flamegraph. Can be called multiple times for different graphs on the same page.
interface EmbeddableFlameGraphOptions { title?: string // Display title (default: 'Profile') filename?: string // Original filename (default: 'profile.pb') primaryColor?: string // Primary color (default: '#ff4444') secondaryColor?: string // Secondary color (default: '#ffcc66') height?: number // Container height in pixels (default: 500)}interface EmbeddableFlameGraphResult { html: string // HTML container div with unique ID script: string // JavaScript code to render into the container}
Key Features
Reusable bundle: The React-pprof bundle is loaded once and cached, improving performance when rendering multiple graphs
No global conflicts: Each graph uses unique IDs and local variables, so multiple graphs can coexist without conflicts
Self-contained: Generated HTML includes all necessary styling and structure
Efficient: Profile data is embedded efficiently and decoded on the client side
Command Line Interface (CLI)
This package includes a CLI utility to generate static HTML flamegraphs from pprof files without requiring a running server.
Installation
Install the CLI globally or use via npx:
# Install globallynpm install -g react-pprof# Or use with npx (no installation required)npx react-pprof profile.pb
This generates optimized HTML templates and JavaScript bundles in the cli-build/ directory.
Supported Profile Formats
The CLI automatically handles both:
Gzipped profiles: Common with @datadog/pprof output (auto-detected)
Uncompressed profiles: Raw pprof binary data
Example Workflow
# 1. Generate a profile (see examples below)curl http://localhost:3000/profile > profile.pb# 2. Build CLI templates (one-time setup)npm run build:cli# 3. Generate static HTML flamegraphreact-pprof profile.pb# 4. Open in browseropen profile.html
The generated HTML includes:
Complete React flamegraph visualization
Interactive tooltips and stack details
WebGL-optimized rendering
All profile data embedded (no server required)
Capturing pprof Profiles
Using @datadog/pprof
To capture CPU profiles in Node.js applications, you can use the @datadog/pprof package:
npm install @datadog/pprof
Requirements: Node.js 18 or greater
Basic CPU Profile Capture
const pprof = require('@datadog/pprof')const fs = require('fs')// Collect a 10-second wall time profileconst profile = await pprof.time.profile({ durationMillis: 10000 // Profile for 10 seconds})// Or...pprof.time.start({ durationMillis: 10000})// Do something ...const profile = pprof.time.stop()// Encode profile data to bufferconst buf = profile.encode()// Save profile data to diskfs.writeFile('cpu-profile.pprof', buf, (err) => { if (err) throw err; console.log('Profile saved to cpu-profile.pprof')})
Example Servers
This repository includes example servers to demonstrate profile generation:
Real Profiling Server (example-server.js)
# Start the real profiling servernode example-server.js# Generate some load to profilecurl http://localhost:3002/loadcurl http://localhost:3002/loadcurl http://localhost:3002/load# Download gzipped profile (automatically handled by CLI)curl http://localhost:3002/profile > real-profile.pb# Generate flamegraphreact-pprof real-profile.pb
Synthetic Profile Server (simple-server.js)
For testing and demonstration, use the synthetic server that generates compatible pprof data:
The synthetic server creates realistic function hierarchies and CPU distributions for demonstration purposes.
Components
This package provides several React components for visualizing pprof profiles. Click on each component name for detailed documentation, props, and usage examples:
Core Components
FullFlameGraph - Complete flame graph with navigation controls, hottest frames bar, and stack details panel
FlameGraphTooltip - Tooltip component for displaying frame information on hover
Getting Started
For most use cases, start with FullFlameGraph as it provides a complete profiling interface out of the box. Use the individual components when you need more control over the layout and functionality.
Data Types
FrameData
Represents a single frame in the flame graph.
interface FrameData { id: string; // Unique identifier for the frame name: string; // Function name value: number; // Frame weight/value depth: number; // Stack depth (0 = root) x: number; // Normalized x position (0-1) width: number; // Normalized width (0-1) functionName: string; // Function name (same as name) fileName?: string; // Source file name lineNumber?: number; // Source line number}
FlameNode
Represents a node in the flame graph tree structure.
Both the <FlameGraph /> and <FullFlameGraph /> components accept several color properties to configure their appearance:
backgroundColor - Background color of the flame graph
textColor - Color of text labels and UI elements
primaryColor - Color for root nodes or nodes near 100% of their parent's weight
secondaryColor - Color for nodes near 0% of their parent's weight
The flame graph uses a gradient of colors between the primary and secondary colors depending on each frame's weight ratio compared to its parent.
// Traditional Red/Orange theme<FullFlameGraph profile={profile} primaryColor="#ff4444" secondaryColor="#ffcc66" backgroundColor="#1e1e1e" textColor="#ffffff"/>// Green theme<FullFlameGraph profile={profile} primaryColor="#2ecc71" secondaryColor="#27ae60" backgroundColor="#1e1e1e" textColor="#ffffff"/>// Blue theme<FullFlameGraph profile={profile} primaryColor="#2563eb" secondaryColor="#7dd3fc" backgroundColor="#2c3e50" textColor="#ffffff"/>
Interactions
Mouse Controls
Click Frame: Zoom in to selected frame
Click Empty Space: Zoom out to root view
Hover Frame: Show tooltip with frame details
Mouse Move: Tooltip follows cursor
Mouse Leave: Hide tooltip
Keyboard Navigation
The flame graph supports full keyboard navigation for accessibility and power users:
Arrow Up (↑): Navigate to the parent frame (zoom out one level in the call stack)
Arrow Down (↓): Navigate to the first child frame (zoom into the largest child by value)
Arrow Left (←): Navigate to the previous sibling frame (move to the frame before the current one at the same stack level)
Arrow Right (→): Navigate to the next sibling frame (move to the frame after the current one at the same stack level)
Escape or Home: Reset zoom to show the complete flame graph
The canvas is focusable (tabIndex=0) and includes appropriate ARIA attributes for screen readers. Keyboard navigation automatically zooms to each selected frame and triggers the onFrameClick callback with the appropriate frame data.
Testing
Running Tests
# Run all testsnpm test# Run tests with UInpm run test:ui# Run specific test suitesnpm run test:flamegraphnpm run test:stack-detailsnpm run test:integration# Update visual snapshotsnpm run test:update-snapshots
Test Coverage
Unit Tests: Component logic and data processing
Integration Tests: Component interaction and communication