Watt Admin 1.0.0: Enhanced Node.js Performance Profiling with Recording Mode

performance monitoring

Discover Watt Admin's new Recording Mode with CPU and Heap Profiling for Node.js applications. Capture performance data, generate flame graphs, and share self-contained HTML reports for easy analysis and collaboration, even offline.

Watt Admin introduces a powerful new Recording Mode, complete with CPU and Heap Profiling. This innovative feature allows users to capture comprehensive application performance data, generate insightful flame graphs, and package all findings into a single, self-contained HTML file for easy sharing, even without an internet connection.

The Challenge: Sharing Performance Insights

Node.js developers often face the challenge of sharing performance insights effectively. While real-time monitoring is excellent for live debugging, communicating complex performance issues, especially for post-mortem analysis or specific scenarios, can be difficult. Screenshots offer limited context, and establishing shared monitoring dashboards isn't always feasible. Watt Admin's new Recording Mode addresses these challenges by enabling detailed profile capture and effortless sharing.

What's New: Record, Profile, Analyze

The new recording capabilities of Watt Admin provide a comprehensive suite of tools:

  • Record complete sessions: Capture all performance metrics and data over a specified duration.
  • Generate flame graphs: Visualize CPU usage and heap allocation to precisely identify performance bottlenecks.
  • Create offline bundles: Consolidate all captured data and visualizations into a single, portable HTML file.
  • Share effortlessly: Distribute the bundle to team members or clients, requiring no special setup or internet access for viewing.

How It Works

Metrics Recording

Every recording session initiates with comprehensive metrics collection, providing a holistic view of your application's health and performance. Watt Admin captures critical data across several categories:

  • Memory Metrics:
    • RSS (Resident Set Size): Monitors total process memory usage.
    • Heap Usage: Tracks total heap, used heap, new space, and old space, crucial for identifying memory leaks and garbage collection patterns.
  • CPU & Event Loop:
    • CPU Usage: Provides per-thread CPU utilization percentages.
    • Event Loop Utilization (ELU): A key indicator of Node.js application health, reflecting the event loop's busyness.
  • HTTP Performance:
    • Request Count & RPS: Measures total requests and throughput over time.
    • Latency Percentiles: Reports P90, P95, and P99 response times to analyze tail latency.
  • HTTP Client (Undici):
    • Connection Pool Stats: Monitors idle, open, pending, queued, and active sockets, offering insights into external service communication.
  • Additional Metrics:
    • WebSocket Connections: Counts active WebSocket connections.
    • Kafka Metrics: If Kafka is in use, tracks produced/consumed messages, producers, consumers, and DLQ statistics.
    • Event Loop Resources: Monitors active handles and requests within the event loop.

All metrics are sampled every second and stored for the entire recording session (up to 600 data points). Upon stopping the recording, this complete metrics history is bundled into the HTML file, offering a detailed timeline for in-depth analysis.

CPU Profiling

Pinpoint performance bottlenecks by visualizing where your application spends its CPU time. To initiate CPU profiling, use the command:

watt-admin --record --profile cpu

After running your application through the desired scenario, press Ctrl+C. Watt Admin will then:

  1. Stop profiling all services within your runtime.
  2. Collect comprehensive CPU flame graph data.
  3. Bundle all recorded metrics and the generated flame graph into a single HTML file.
  4. Automatically open this file in your default browser.

The resulting interactive flame graph clearly illustrates which functions are consuming CPU cycles, facilitating straightforward identification of optimization opportunities.

Heap Profiling

Effectively identify and address memory leaks while gaining insights into allocation patterns with heap profiling:

watt-admin --record --profile heap

Heap profiling provides crucial information, including:

  • Which code segments are responsible for the highest memory allocations.
  • Memory allocation trends over time.
  • Potential sources of memory leaks.
  • Object retention paths.

This feature is invaluable for debugging elusive memory issues that manifest under specific operational conditions.

Real-World Use Cases

Watt Admin's recording mode offers practical benefits across various development scenarios:

  • Debugging Production Issues Locally: Replicate a production problem in a local environment, record a CPU profiling session, and share the comprehensive analysis with your team. The self-contained HTML bundle allows anyone to explore flame graphs and metrics without needing to replicate the original setup.
  • Performance Reviews: Prior to merging significant code changes, record a profiling session to quantitatively demonstrate performance characteristics. Attach the HTML file to pull requests, enabling reviewers to directly assess the real-world impact of proposed optimizations.
  • Team Knowledge Sharing: Document and share intriguing performance patterns by recording them and distributing the bundle via communication platforms like Slack. Colleagues can then interactively explore flame graphs and metrics without any setup.
  • Client Reporting: When demonstrating application performance issues to clients, generate a recording with clear flame graphs to visually pinpoint bottlenecks. The portable HTML format ensures professional and easily shareable performance analysis.

The Technical Details

Watt Admin's recording mode is built upon Platformatic's integrated profiling capabilities, ensuring robust and standard-compliant operation:

  • Automatic Service Discovery: Automatically profiles all applications operating within your Platformatic runtime.
  • Standards-Based Profiling: Utilizes V8's native CPU and heap profilers for accurate data capture.
  • pprof Format: Stores all profiling data in the widely recognized and industry-standard pprof format.
  • Interactive Visualization: Leverages react-pprof to provide an intuitive and interactive experience for exploring flame graphs.
  • Complete Data Capture: Embeds all collected metrics, logs, and profiling data directly into window.LOADED_JSON within the bundle.

The generated HTML bundle is designed for complete self-containment, encapsulating:

  • All necessary JavaScript, CSS, and assets, inlined for portability.
  • The entire metrics history from the recording session.
  • Detailed flame graph data for all profiled services.
  • A fully interactive user interface for data exploration.

This ensures that the bundle has no external dependencies or network requests; simply open the file to begin your analysis.

Getting Started

Prerequisites

Important: Watt Admin is specifically designed for applications running on Platformatic Watt. If you haven't set up a Watt application yet, please refer to the Quick Start Guide.

Installation

Install Watt Admin globally using npm:

npm i @platformatic/watt-admin -g

Alternatively, you can use npx to run it directly:

npx wattpm admin --record --profile cpu

Basic Workflow

  1. Start a recording session: 
    watt-admin --record --profile cpu
  2. Run your application through the specific scenario you wish to analyze.
  3. Stop recording by pressing Ctrl+C.
  4. Analyze the automatically generated HTML bundle that opens in your browser.
  5. Share the resulting bundle file with your team for collaborative review.

Under the Hood: How Recording Works

When Watt Admin is initiated with the --record flag, the following sequence of events occurs:

  1. Discovery: Watt Admin identifies your Platformatic runtime via the RuntimeApiClient.
  2. Connection: It establishes a connection to the runtime's administrative API.
  3. Profiling Start: The startApplicationProfiling() method is invoked on each detected application.
  4. Metrics Collection: Performance metrics are continuously gathered at regular intervals.
  5. User Interaction: You interact with your application during the profiling period.
  6. SIGINT Handling: Upon pressing Ctrl+C, a graceful shutdown process commences.
  7. Profiling Stop: The stopApplicationProfiling() method is called to retrieve all profiling data.
  8. Data Bundling: Profiling data (.pb files) and all other relevant information are written and embedded into a single HTML file.
  9. Auto-Launch: The newly generated bundle is automatically opened in your default web browser.

The final output file, typically found at web/frontend/dist/index.html, is completely self-contained and ready for offline analysis.

What's Next

Recording mode represents an initial step in enhancing Watt Admin's profiling capabilities. Future explorations include:

  • Custom Time Ranges: The ability to record performance data within specific, user-defined time windows.
  • Comparison Mode: Features allowing for side-by-side comparison of multiple recording sessions.
  • Export Formats: Expanding export options to support integration with diverse analytical tools.
  • Annotations: Functionality to mark and highlight specific events or points of interest during a recording.

Your feedback is highly valued as we continue to develop these features. We encourage you to try the recording mode and share your experiences!

Try It Today

Recording and profiling features are immediately available in Watt Admin. To get started, update to the latest version:

npm i @platformatic/watt-admin -g

Then, begin your profiling session:

watt-admin --record --profile cpu

Happy profiling!

Resources

Get Involved

For questions or feedback, connect with the community: