Today, we're excited to announce a revolutionary new approach to CPU profiling and flamegraph visualization in Node.js. We've built a complete profiling ecosystem that spans from individual applications to enterprise microservice architectures, with a beautiful visualization that makes performance optimization intuitive and actionable.
A Complete Profiling Ecosystem
Our comprehensive solution consists of three powerful components working together:
@platformatic/flame: Universal profiling toolkit for any Node.js application
react-pprof: WebGL-powered visualization components and standalone HTML generation
Watt Integration: Built-in profiling for the Node.js Application Serveri with service-level granularity
Together, these tools provide everything you need for Node.js performance analysis, from development to production.
Our profiling toolkit is designed from the ground up for integration into any Node.js application or development workflow:
Zero-Config Profiling: Drop-in profiling for any Node.js script with no code changes required
Integration-First Design: Explicitly built to integrate into existing applications, CI/CD pipelines, and development tools
Signal-Based Control: Start/stop profiling using SIGUSR2 signals - perfect for production environments
Programmatic API: Rich JavaScript API designed for tooling integration and automation
Cross-Platform CLI: Simple commands that work consistently across macOS, Linux, and Windows
Standard Output Format: Generates industry-standard pprof files compatible with the entire ecosystem
flame run server.js
flame run --manual server.js
kill -USR2 <PID>
kill -USR2 <PID>
🎨 react-pprof: WebGL-Powered Visualization
Our React component library brings professional-grade flamegraph rendering to the web:
WebGL-Accelerated Performance: Smooth, responsive rendering even with massive profile datasets
Interactive Exploration: Click, zoom, and navigate through your performance data with fluid animations
Rich Stack Details: Complete call hierarchy visualization with parent/child relationships
Customizable Theming: Multiple color schemes and full styling control
TypeScript Support: First-class TypeScript integration with comprehensive type definitions
Static HTML Generation: Generate standalone HTML flamegraphs with our CLI tool
import React, { useState, useEffect } from 'react'
import { FlameGraph, StackDetails, fetchProfile } from 'react-pprof'
function ProfileViewer({ profileUrl }) {
const [profile, setProfile] = useState(null)
const [selectedFrame, setSelectedFrame] = useState(null)
// Load the profile data if not already loaded
useEffect(() => {
fetchProfile(profileUrl)
.then(setProfile)
.catch(err => setError(err.message))
.finally(() => setLoading(false))
}, [profileUrl])
// Show a loading message until the profile is ready
if (!profile) {
return (
<div style={{ display: 'flex', height: '100vh' }}>
<div>Loading...</div>
</div>
)
}
// Render a flamegraph with a stack details panel to inspect frames
return (
<div style={{ display: 'flex', height: '100vh' }}>
<FlameGraph
profile={profile}
onFrameClick={(frame, stack, children) => {
setSelectedFrame(frame)
}}
zoomOnScroll={true}
/>
<StackDetails selectedFrame={selectedFrame} />
</div>
)
}
🏗️ Watt: Enterprise Application Server Integration
Watt, Platformatic's Node.js application server, provides built-in profiling capabilities designed for microservice architectures:
Service-Level Profiling: Profile individual microservices or entire applications with granular control
Zero Configuration: Built-in profiler with no additional setup required
Production Ready: Minimal overhead (~1-5% CPU) suitable for production environments
Remote Profiling: Profile services running in any environment
Automatic Discovery: Auto-detects running services and provides simple commands
wattpm pprof start
wattpm pprof start api-service database-service
wattpm pprof stop
flame generate pprof-api-service-*.pb
flame generate pprof-database-service-*.pb
What is a Flamegraph?
A flamegraph is a powerful visualization technique that shows precisely where your Node.js application spends its CPU time. Think of it as an X-ray for your code's performance.
How to Read a Flamegraph
Width = Time: Wider sections represent functions that consumed more CPU time
Height = Call Depth: Taller stacks show deeper function call chains
Colors = Heat: Warmer colors (reds/oranges) indicate functions using more CPU at their stack level
Click to Zoom: Interactive exploration lets you drill down into specific code paths
What to Look For:
Wide Plateaus: Functions consuming significant CPU time - prime optimization candidates
Tall Spires: Deep call stacks that may indicate complex or recursive logic
Multiple Peaks: Different execution phases or code paths in your application
Dominant Sections: The largest areas show where most CPU time is spent
Flamegraphs turn complex performance data into an intuitive visual map, making it easy to spot bottlenecks and understand your application's behavior at a glance.
The Complete Workflow
Here's how easy it is to profile your Node.js applications:
npm install -g @platformatic/flame
npm install react-pprof
Package Links:
2. Profile Your Application
flame run your-app.js
curl http://localhost:3000/api/heavy-computation
curl http://localhost:3000/api/heavy-computation
3. View the Results
open cpu-profile-*.html
flame generate cpu-profile-*.pb
Built on Open Source Foundation
Our profiling ecosystem builds upon excellent prior work in Node.js performance analysis. We're particularly inspired by 0x, the pioneering flamegraph tool for Node.js created by David Mark Clements, which introduced many developers to the power of flamegraph visualization. The success of 0x later led to Clinic.js, a comprehensive performance toolkit created by NearForm and built on top of 0x's foundation.
While these tools provided valuable inspiration, our approach represents a novel direction: combining modern web technologies with integration-first design to create a unified ecosystem that spans from individual development to enterprise microservice architectures.
Our toolkit is powered by Datadog's generous open source contribution: the @datadog/pprof library. This battle-tested Node.js profiling library provides the core CPU sampling and pprof data export functionality, making our entire toolkit possible.
We're grateful to both the 0x project for pioneering Node.js flamegraph analysis and to Datadog for open sourcing this critical infrastructure, which together enable the Node.js community to have access to production-grade profiling capabilities that were previously only available in enterprise monitoring solutions.
Technical Excellence
Both packages are built with production-grade quality in mind:
react-pprof Features:
WebGL Rendering Pipeline: Custom shaders for optimal performance
Responsive Design: Works seamlessly across desktop and mobile
Accessibility Support: Full keyboard navigation and ARIA compliance
Visual Regression Testing: Pixel-perfect consistency across updates
Storybook Integration: Comprehensive component documentation with Storybook
Integration-First Architecture: Designed for seamless embedding in existing applications and tools
Cross-Platform Support: Works consistently across macOS, Linux, and Windows environments
Protocol Buffer Output: Standard pprof format for compatibility with entire profiling ecosystem
Automatic Compression: Efficient gzipped profile storage for CI/CD and automation
Process Management: Clean signal handling perfect for production and development workflows
Flexible Control: Auto-start mode for development, manual mode for production and CI/CD
We've tested both tools extensively in production environments:
Profiling Overhead Analysis
Comprehensive benchmarks show minimal performance impact when profiling is active. Testing was conducted with 10 concurrent connections over 10 seconds across different computation workloads:
Express.js Framework Results:
| Endpoint Type | Load Level | Without Profiling | With Profiling | Throughput Overhead | Latency Overhead |
| Health Check | Minimal | 13,571 req/s | 13,752 req/s | -1.3% | -6.3% |
| Light Computation | Low | 10,187 req/s | 9,979 req/s | +2.0% | +12.0% |
| Medium Computation | Moderate | 71 req/s | 66 req/s | +6.1% | +6.3% |
| Heavy Computation | High | 295 req/s | 291 req/s | +1.3% | +1.4% |
| Mixed Computation | Very High | 56 req/s | 53 req/s | +5.2% | +5.8% |
Express Summary: Average throughput overhead of 2.7% and latency overhead of 3.9%
Fastify Framework Results:
| Endpoint Type | Load Level | Without Profiling | With Profiling | Throughput Overhead | Latency Overhead |
| Health Check | Minimal | 41,174 req/s | 38,747 req/s | +5.9% | 0.0% |
| Light Computation | Low | 35,056 req/s | 32,847 req/s | +6.3% | 0.0% |
| Medium Computation | Moderate | 3,235 req/s | 3,126 req/s | +3.4% | +4.2% |
| Heavy Computation | High | 345 req/s | 336 req/s | +2.6% | +2.6% |
| Mixed Computation | Very High | 311 req/s | 304 req/s | +2.3% | +2.3% |
Fastify Summary: Average throughput overhead of 4.1% and latency overhead of 1.8%
These results demonstrate that @platformatic/flame adds minimal overhead even under high load scenarios, making it suitable for production profiling.
Our React components deliver exceptional rendering performance:
Large Profiles: Handles profiles with 100k+ frames smoothly
Memory Efficiency: Optimized data structures and WebGL resource management
Fast Startup: Sub-second initialization for most profiles
Responsive Interaction: 60fps zooming and panning even on mobile devices
Integration Examples
const express = require('express')
const app = express()
app.get('/heavy', (req, res) => {
const result = performComplexCalculation()
res.json(result)
})
app.listen(3000)
flame run server.js
curl http://localhost:3000/heavy
curl http://localhost:3000/heavy
curl http://localhost:3000/heavy
React Application Integration
import { FlameGraph, StackDetails } from 'react-pprof'
function ProfileDashboard({ profile, handleFrameSelection, selectedFrame, stackTrace }) {
return (
<div className="profiling-dashboard">
<FlameGraph
profile={profile}
primaryColor="#3498db"
secondaryColor="#87ceeb"
backgroundColor="#2c3e50"
onFrameClick={handleFrameSelection}
/>
<StackDetails
selectedFrame={selectedFrame}
stackTrace={stackTrace}
/>
</div>
)
}
Watt Application Server Integration
Watt, Platformatic's Node.js application server, includes built-in CPU profiling capabilities that work seamlessly with our flamegraph ecosystem:
wattpm pprof start
curl http://localhost:3000/api/users
curl http://localhost:3000/api/orders
wattpm pprof stop
flame generate pprof-api-service-*.pb
flame generate pprof-database-service-*.pb
Watt Profiling Features:
Service-Level Profiling: Profile individual microservices or entire applications
Zero Configuration: Built-in profiler with no additional setup required
Production Ready: Minimal overhead (~1-5% CPU) suitable for production environments
Remote Profiling: Profile services running in any environment
Standard Output: Generates pprof-compatible files that work with our visualization tools
This integration makes it incredibly easy to profile complex microservice architectures and identify performance bottlenecks across your entire application stack.
For a complete guide on profiling with Watt, including advanced workflows and best practices, see our Profiling with Watt guide.
What Makes This Special
Unlike traditional profiling tools, our approach combines:
Integration-First Design: @platformatic/flame is built to integrate seamlessly into any existing Node.js application, CI/CD pipeline, or development tool
Application Server Integration: Built-in profiling in Watt for microservice architectures with service-level granularity
Modern Web Technology: React components with WebGL acceleration
Zero-Config Experience: Drop-in profiling with no code changes required
Production Ready: Battle-tested performance and reliability in real-world applications
Ecosystem Compatibility: Standard pprof output works with the entire profiling toolchain
Beautiful Visualization: Professional-grade flamegraphs that actually help you understand your code
Getting Started Today
Both packages are available on npm and ready for production use:
npm install -g @platformatic/flame
npm install react-pprof
npm Packages:
Visit our repositories for comprehensive documentation:
We believe great developer tools should be powerful yet simple, beautiful yet functional. These packages represent our vision for the future of performance analysis in Node.js - where profiling integrates seamlessly into any workflow, is as easy as running a single command, and understanding your code's performance is as simple as exploring an interactive flamegraph.
Try them out today and let us know what you think! We're excited to see how the Node.js community uses these tools to build faster, more efficient applications.
Built with ❤️ by the Platformatic team. We're making Node.js development faster, easier, and more enjoyable for everyone.
Special thanks to Datadog for open-sourcing the @datadog/pprof library, which provides the foundational CPU profiling capabilities that power our entire ecosystem. Their commitment to open source enables the Node.js community to benefit from enterprise-grade performance analysis tools.
