We're excited to announce a powerful new feature in Watt Admin: Recording Mode with CPU and Heap Profiling. Now you can capture your application's performance data, generate flame graphs, and share everything in a single, self-contained HTML file—no internet connection required.
As Node.js developers, we've all been there: you've discovered a performance issue, captured some data, and now need to share it with your team. But how do you effectively communicate what you're seeing? Screenshots don't tell the whole story, and setting up monitoring dashboards for everyone isn't always practical.
Previously, Watt Admin provided real-time monitoring—perfect for live debugging. But what about post-mortem analysis? What if you need to capture a performance profile during a specific scenario, or share detailed metrics with a colleague who isn't running your application?
That's where Recording Mode comes in.
What's New: Record, Profile, Analyze
With the new recording capabilities, Watt Admin can now:
📹 Record complete sessions: Capture all metrics and performance data over time
🔥 Generate flame graphs: Profile CPU usage or heap allocation to identify bottlenecks
📦 Create offline bundles: Package everything into a single HTML file
🤝 Share effortlessly: Send the bundle to anyone—no setup required
How It Works
Metrics Recording
At the core of every recording session is comprehensive metrics collection. Watt Admin captures a complete picture of your application's health and performance:
Memory Metrics
RSS (Resident Set Size): Total process memory usage
Heap Usage: Total heap, used heap, new space, and old space—essential for tracking memory leaks and garbage collection behavior
CPU & Event Loop
HTTP Performance
Request Count & RPS: Total requests and throughput over time
Latency Percentiles: P90, P95, and P99 response times to understand your tail latency
HTTP Client (Undici)
Connection Pool Stats: Idle, open, pending, queued, and active sockets
Track how your application communicates with external services
Additional Metrics
WebSocket Connections: Active WebSocket connection count
Kafka Metrics: Produced/consumed messages, producers, consumers, and DLQ stats (if using Kafka)
Event Loop Resources: Active handles and requests in the event loop
All metrics are sampled every second and stored for the duration of your recording session (up to 600 data points). When you stop recording, this entire metrics history is bundled into the HTML file, giving you a complete timeline to analyze.
CPU Profiling
Identify performance bottlenecks by visualizing where your application spends CPU time:
watt-admin --record --profile cpu
Run your application through the scenario you want to analyze, then press Ctrl+C. Watt Admin will:
Stop profiling all services in your runtime
Collect CPU flame graph data
Bundle all metrics and the flame graph into a single HTML file
Automatically open it in your browser
The resulting flame graph shows you exactly which functions are consuming CPU cycles, making it easy to spot optimization opportunities.
Heap Profiling
Track down memory leaks and understand allocation patterns:
watt-admin --record --profile heap
Heap profiling reveals:
Which parts of your code allocate the most memory
Memory allocation patterns over time
Potential memory leak sources
Object retention paths
Perfect for debugging those mysterious memory issues that only appear under specific conditions.
Real-World Use Cases
Debugging Production Issues Locally
Reproduce a production issue in your local environment, record a session with CPU profiling, and share the complete analysis with your team. No need for everyone to set up the same environment—they can explore the flame graph and metrics directly from the HTML bundle.
Before merging a significant change, record a profiling session to demonstrate its performance characteristics. Attach the HTML file to your pull request so reviewers can see the real-world impact of your optimizations.
Team Knowledge Sharing
Found an interesting performance pattern? Record it and share the bundle in Slack or your team chat. Your colleagues can explore the interactive flame graph and metrics without any setup.
Client Reporting
Need to show a client why their application is slow? Generate a recording with clear flame graphs that visually demonstrate the bottlenecks. The self-contained HTML makes it easy to share professional performance analysis.
The Technical Details
Recording mode leverages Platformatic's built-in profiling capabilities:
Automatic service discovery: Profiles all applications in your Platformatic runtime
Standards-based profiling: Uses V8's built-in CPU and heap profilers
pprof format: Stores profiling data in the industry-standard pprof format
Interactive visualization: Uses react-pprof for exploring flame graphs
Complete capture: Embeds metrics, logs, and profiling data in window.LOADED_JSON
The generated HTML bundle is truly self-contained—it includes:
All JavaScript, CSS, and assets inlined
Complete metrics history from the recording session
Flame graph data for all profiled services
Interactive UI for exploring the data
No external dependencies. No network requests. Just open and explore.
Getting Started
Prerequisites
Important: Watt Admin is designed specifically for applications running on Platformatic Watt. If you don't have a Watt application yet, follow the Quick Start Guide to create one.
Installation
Install Watt Admin globally:
npm i @platformatic/watt-admin -g
Or use it directly with npx:
npx wattpm admin --record --profile cpu
Basic Workflow
Start a recording session:
watt-admin --record --profile cpu
Run your application through the scenario you want to analyze
Stop recording by pressing Ctrl+C
Analyze the automatically-opened HTML bundle
Share the bundle file with your team
Under the Hood: How Recording Works
When you start Watt Admin with --record, here's what happens:
Discovery: Watt Admin discovers your Platformatic runtime using the RuntimeApiClient
Connection: Connects to the runtime's admin API
Profiling start: Calls startApplicationProfiling() on each application
Metrics collection: Continuously collects metrics at regular intervals
User interaction: You use your application while profiling runs
SIGINT handling: When you press Ctrl+C, graceful shutdown begins
Profiling stop: Calls stopApplicationProfiling() to get the profiling data
Data bundling: Writes profiling data (.pb files) and embeds everything in HTML
Auto-launch: Opens the generated bundle in your default browser
The resulting file lives in web/frontend/dist/index.html and contains everything needed for offline analysis.
What's Next
Recording mode is just the beginning. We're exploring additional profiling capabilities:
Custom time ranges: Record specific time windows
Comparison mode: Compare multiple recordings side-by-side
Export formats: Additional export options for different tools
Annotations: Mark specific events during recording
We'd love to hear your feedback! Try recording mode and let us know what you think.
Try It Today
Recording and profiling are available now in Watt Admin. Update to the latest version:
npm i @platformatic/watt-admin -g
Then start profiling:
watt-admin --record --profile cpu
Happy profiling! 🔥
Resources
Get Involved
Have questions or feedback? Connect with us:
