package
React component for visualizing pprof with WebGL
npm install react-pprofGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
A React component for visualizing pprof profiles using WebGL.
ivan-tymoshenko
ivan@tymoshenko.me
npm install react-pprofimport 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 <div>Loading profile...</div>
if (error) return <div>Error: {error.message}</div>
if (!profile) return <div>No profile data</div>
return (
<FullFlameGraph
profile={profile}
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:
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 = `
<!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>
`getFlamegraphBundle()
Returns the reusable React-pprof bundle code (cached after first call). Include this once in your page before rendering any graphs.
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.
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
}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:
# Install globally
npm install -g react-pprof
# Or use with npx (no installation required)
npx react-pprof profile.pb# Basic usage
react-pprof profile.pb
# Custom output file
react-pprof -o flamegraph.html profile.pb
# Help
react-pprof --helpBefore using the CLI, build the static templates:
npm run build:cliThis generates optimized HTML templates and JavaScript bundles in the cli-build/ directory.
The CLI automatically handles both:
# 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 flamegraph
react-pprof profile.pb
# 4. Open in browser
open profile.htmlThe generated HTML includes:
To capture CPU profiles in Node.js applications, you can use the @datadog/pprof package:
npm install @datadog/pprofRequirements: Node.js 18 or greater
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')
})This repository includes example servers to demonstrate profile generation:
# Start the real profiling server
node example-server.js
# Generate some load to profile
curl http://localhost:3002/load
curl http://localhost:3002/load
curl http://localhost:3002/load
# Download gzipped profile (automatically handled by CLI)
curl http://localhost:3002/profile > real-profile.pb
# Generate flamegraph
react-pprof real-profile.pbFor testing and demonstration, use the synthetic server that generates compatible pprof data:
# Start the synthetic server
node simple-server.js
# Download synthetic profile
curl http://localhost:3001/profile > synthetic-profile.pb
# Generate flamegraph
react-pprof synthetic-profile.pbThe synthetic server creates realistic function hierarchies and CPU distributions for demonstration purposes.
This package provides several React components for visualizing pprof profiles. Click on each component name for detailed documentation, props, and usage examples:
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.
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
}Represents a node in the flame graph tree structure.
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
}Both the <FlameGraph /> and <FullFlameGraph /> components accept several color properties to configure their appearance:
backgroundColor - Background color of the flame graphtextColor - Color of text labels and UI elementsprimaryColor - Color for root nodes or nodes near 100% of their parent's weightsecondaryColor - 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.
// 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"
/>The flame graph supports full keyboard navigation for accessibility and power users:
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.
# Run all tests
npm test
# Run tests with UI
npm run test:ui
# Run specific test suites
npm run test:flamegraph
npm run test:stack-details
npm run test:integration
# Update visual snapshots
npm run test:update-snapshots# Clone repository
git clone https://github.com/platformatic/react-pprof.git
cd react-pprof
# Install dependencies
npm install
# Start development server
npm run storybookEstimated unpacked size across 8 packages.
14.6 MB
Includes dependencies.
5 direct · 1 outdated
^19.1.0
19.3.1
^3.4.3
3.4.4
^19.1.0
19.3.1
^7.5.3
8.8.1
^2.2.1
2.4.0