React component for visualizing pprof with WebGL
npm install react-pprofA React component for visualizing pprof profiles using WebGL.


- ๐ WebGL-accelerated rendering for smooth performance with large datasets
- ๐จ Customizable theming with multiple color schemes
- ๐ Interactive zoom and pan with smooth animations
- ๐ Stack trace visualization with complete call hierarchy
- ๐ฏ Frame details panel showing children and parent relationships
- ๐ฑ Responsive design that works on all screen sizes
- ๐ง TypeScript support with full type definitions
- ๐งช Comprehensive testing with visual regression tests
- โก High performance optimized for large profile datasets
- ๐ป Command Line Interface for generating static HTML flamegraphs
``bash`
npm install react-pprof
`tsx
import React, { useState, useEffect } from 'react'
import { FullFlameGraph, fetchProfile } from 'react-pprof'
function App() {
const [profile, setProfile] = useState(null)
const [loading, setLoading] = useState(true)
const [error, setError] = useState(null)
useEffect(() => {
fetchProfile('/path/to/profile.pprof')
.then(setProfile)
.catch(setError)
.finally(() => setLoading(false))
}, [])
if (loading) return
return (
height={600}
showHottestFrames={true}
showControls={true}
showStackDetails={true}
/>
)
}
`
For programmatic generation of embeddable flamegraphs (e.g., for middleware or dynamic HTML generation), use the embedding API that supports rendering multiple graphs efficiently:
`typescript
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 profiles
const 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 response
const fullPage =
`
getFlamegraphBundle()
Returns the reusable React-pprof bundle code (cached after first call). Include this once in your page before rendering any graphs.
`typescript`
Promise<{ bundle: string }>
generateEmbeddableFlameGraph(profileBuffer, options)
Generates embeddable HTML and JavaScript for a single flamegraph. Can be called multiple times for different graphs on the same page.
`typescript
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
}
`
- 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
This package includes a CLI utility to generate static HTML flamegraphs from pprof files without requiring a running server.
Install the CLI globally or use via npx:
`bashInstall globally
npm install -g react-pprof
$3
`bash
Basic usage
react-pprof profile.pbCustom output file
react-pprof -o flamegraph.html profile.pbHelp
react-pprof --help
`$3
Before using the CLI, build the static templates:
`bash
npm run build:cli
`This generates optimized HTML templates and JavaScript bundles in the
cli-build/ directory.$3
The CLI automatically handles both:
- Gzipped profiles: Common with @datadog/pprof output (auto-detected)
- Uncompressed profiles: Raw pprof binary data
$3
`bash
1. Generate a profile (see examples below)
curl http://localhost:3000/profile > profile.pb2. Build CLI templates (one-time setup)
npm run build:cli3. Generate static HTML flamegraph
react-pprof profile.pb4. Open in browser
open 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
$3
To capture CPU profiles in Node.js applications, you can use the
@datadog/pprof package:`bash
npm install @datadog/pprof
`Requirements: Node.js 18 or greater
#### Basic CPU Profile Capture
`javascript
const pprof = require('@datadog/pprof')
const fs = require('fs')// Collect a 10-second wall time profile
const 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 buffer
const buf = profile.encode()
// Save profile data to disk
fs.writeFile('cpu-profile.pprof', buf, (err) => {
if (err) throw err;
console.log('Profile saved to cpu-profile.pprof')
})
`$3
This repository includes example servers to demonstrate profile generation:
#### Real Profiling Server (example-server.js)
`bash
Start the real profiling server
node example-server.jsGenerate some load to profile
curl http://localhost:3002/load
curl http://localhost:3002/load
curl http://localhost:3002/loadDownload gzipped profile (automatically handled by CLI)
curl http://localhost:3002/profile > real-profile.pbGenerate flamegraph
react-pprof real-profile.pb
`#### Synthetic Profile Server (simple-server.js)
For testing and demonstration, use the synthetic server that generates compatible pprof data:
`bash
Start the synthetic server
node simple-server.jsDownload synthetic profile
curl http://localhost:3001/profile > synthetic-profile.pbGenerate flamegraph
react-pprof synthetic-profile.pb
`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:
$3
- FullFlameGraph - Complete flame graph with navigation controls, hottest frames bar, and stack details panel
- FlameGraph - Core WebGL-powered flame graph visualization component
- StackDetails - Detailed panel showing stack trace and child frames
$3
- HottestFramesBar - Horizontal bar showing frames sorted by self-time
- HottestFramesControls - Navigation controls for stepping through hottest frames
- FrameDetails - Compact frame information display
$3
- FlameGraphTooltip - Tooltip component for displaying frame information on hover
$3
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
$3
Represents a single frame in the flame graph.
`tsx
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
}
`$3
Represents a node in the flame graph tree structure.
`tsx
interface FlameNode {
id: string; // Unique identifier
name: string; // Function name
value: number; // Frame weight/value
children: FlameNode[]; // Child frames
parent?: FlameNode; // Parent frame
x: number; // Normalized x position (0-1)
width: number; // Normalized width (0-1)
depth: number; // Stack depth (0 = root)
fileName?: string; // Source file name
lineNumber?: number; // Source line number
}
`Theming
Both the
and 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 weightThe flame graph uses a gradient of colors between the primary and secondary colors depending on each frame's weight ratio compared to its parent.
`tsx
// Traditional Red/Orange theme
profile={profile}
primaryColor="#ff4444"
secondaryColor="#ffcc66"
backgroundColor="#1e1e1e"
textColor="#ffffff"
/>// Green theme
profile={profile}
primaryColor="#2ecc71"
secondaryColor="#27ae60"
backgroundColor="#1e1e1e"
textColor="#ffffff"
/>
// Blue theme
profile={profile}
primaryColor="#2563eb"
secondaryColor="#7dd3fc"
backgroundColor="#2c3e50"
textColor="#ffffff"
/>
`Interactions
$3
- 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
$3
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
$3
`bash
Run all tests
npm testRun tests with UI
npm run test:uiRun specific test suites
npm run test:flamegraph
npm run test:stack-details
npm run test:integrationUpdate visual snapshots
npm run test:update-snapshots
`$3
- Unit Tests: Component logic and data processing
- Integration Tests: Component interaction and communication
- Visual Regression Tests: Pixel-perfect UI consistency
- Performance Tests: WebGL performance benchmarks
- Accessibility Tests: Keyboard navigation and ARIA support
Development
$3
`bash
Clone repository
git clone https://github.com/platformatic/react-pprof.git
cd react-pprofInstall dependencies
npm installStart development server
npm run storybook
``