https://github.com/platformatic/react-pprof
React component for visualizing pprof with WebGL
https://github.com/platformatic/react-pprof
Last synced: about 2 months ago
JSON representation
React component for visualizing pprof with WebGL
- Host: GitHub
- URL: https://github.com/platformatic/react-pprof
- Owner: platformatic
- License: apache-2.0
- Created: 2025-07-21T12:03:18.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-12-24T13:40:20.000Z (3 months ago)
- Last Synced: 2025-12-26T01:49:06.008Z (3 months ago)
- Language: TypeScript
- Size: 38.5 MB
- Stars: 32
- Watchers: 1
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Notice: NOTICE
Awesome Lists containing this project
README
# react-pprof
A React component for visualizing pprof profiles using WebGL.
[](https://github.com/platformatic/react-pprof/actions/workflows/ci.yml)
[](https://github.com/platformatic/react-pprof/actions/workflows/lint.yml)
## Features
- 🚀 **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
## Installation
```bash
npm install react-pprof
```
## Quick Start
```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
Loading profile...
if (error) return Error: {error.message}
if (!profile) return No profile data
return (
)
}
```
## 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:
```bash
# Install globally
npm install -g react-pprof
# Or use with npx (no installation required)
npx react-pprof profile.pb
```
### CLI Usage
```bash
# Basic usage
react-pprof profile.pb
# Custom output file
react-pprof -o flamegraph.html profile.pb
# Help
react-pprof --help
```
### Building CLI Templates
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.
### 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
```bash
# 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)
## Capturing pprof Profiles
### Using @datadog/pprof
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')
})
```
### Example Servers
This repository includes example servers to demonstrate profile generation:
#### Real Profiling Server (example-server.js)
```bash
# 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
```
#### 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.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.
## 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](src/components/FullFlameGraph.md)** - Complete flame graph with navigation controls, hottest frames bar, and stack details panel
- **[FlameGraph](src/components/FlameGraph.md)** - Core WebGL-powered flame graph visualization component
- **[StackDetails](src/components/StackDetails.md)** - Detailed panel showing stack trace and child frames
### Navigation Components
- **[HottestFramesBar](src/components/HottestFramesBar.md)** - Horizontal bar showing frames sorted by self-time
- **[HottestFramesControls](src/components/HottestFramesControls.md)** - Navigation controls for stepping through hottest frames
- **[FrameDetails](src/components/FrameDetails.md)** - Compact frame information display
### Utility Components
- **[FlameGraphTooltip](src/components/FlameGraphTooltip.md)** - 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.
```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
}
```
### FlameNode
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 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.
```tsx
// Traditional Red/Orange theme
// Green theme
// Blue theme
```
## 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
## Testing
### Running Tests
```bash
# 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
```
### Test Coverage
- **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
### Setup
```bash
# Clone repository
git clone https://github.com/platformatic/react-pprof.git
cd react-pprof
# Install dependencies
npm install
# Start development server
npm run storybook
```