A 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

npm install react-pprof

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 <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}
    />
  )
}

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 --help

Before using the CLI, build the static templates:

npm run build:cli

This generates optimized HTML templates and JavaScript bundles in the cli-build/ directory.

The CLI automatically handles both:

• Gzipped profiles: Common with @datadog/pprof output (auto-detected)
• Uncompressed profiles: Raw pprof binary data

# 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.html

The generated HTML includes:

• Complete React flamegraph visualization
• Interactive tooltips and stack details
• WebGL-optimized rendering
• All profile data embedded (no server required)

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

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.pb

For 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.pb

The 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:

• 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

• HottestFramesBar - Horizontal bar showing frames sorted by self-time
• HottestFramesControls - Navigation controls for stepping through hottest frames
• FrameDetails - Compact frame information display

• FlameGraphTooltip - Tooltip component for displaying frame information on hover

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 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"
/>

• 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

# 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

• 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

# Clone repository
git clone https://github.com/platformatic/react-pprof.git
cd react-pprof

# Install dependencies
npm install

# Start development server
npm run storybook