CPU Profiling with --prof and clinic.js

Intermediate15 min

Profile Node.js CPU usage to find performance bottlenecks using built-in V8 profiler and clinic.js flame charts.

Prerequisites

-Node.js installed
-npm install -g clinic (for clinic.js)

Steps

Profile with the built-in V8 profiler

Start Node.js with the --prof flag to generate a V8 CPU profile log file.

$ node --prof app.js

Run your workload against the app while profiling. The log is written when the process exits.

Process the V8 profile log

Convert the raw V8 log into a human-readable summary showing where CPU time was spent.

$ node --prof-process isolate-*.log > profile.txt

Review the profile results

Examine the processed profile to identify hot functions and optimization opportunities.

$ # Look at the 'Summary' section first: head -50 profile.txt # Then check 'Bottom up (heavy) profile' for hot functions: grep -A 30 'Bottom up' profile.txt | head -40

Focus on the 'ticks' column. Functions with the most ticks are consuming the most CPU time.

Use clinic.js flame for visual profiling

Generate an interactive flame chart to visually identify CPU bottlenecks in your application.

$ clinic flame -- node app.js

Wider bars in the flame chart mean more CPU time. Look for unexpectedly wide bars in your own code (not Node internals).

Profile with Chrome DevTools Performance tab

Use the DevTools Performance tab for interactive CPU profiling with timeline and call tree views.

$ node --inspect app.js # In Chrome DevTools: # 1. Go to Performance tab # 2. Click Record # 3. Run your workload # 4. Stop recording and analyze

Full Script

full-script.sh

#!/bin/bash
set -euo pipefail

# Node.js CPU Profiling Script

APP_FILE="${1:-app.js}"
DURATION="${2:-30}"

echo "==> Profiling ${APP_FILE} for ${DURATION} seconds..."

# Clean up old profiles
rm -f isolate-*.log profile.txt

echo "==> Method 1: V8 --prof profiling..."
timeout ${DURATION} node --prof "${APP_FILE}" 2>/dev/null || true

if ls isolate-*.log 1>/dev/null 2>&1; then
  echo "==> Processing V8 profile log..."
  node --prof-process isolate-*.log > profile.txt
  echo ""
  echo "==> Profile Summary:"
  head -30 profile.txt
  echo ""
  echo "Full profile saved to: profile.txt"
else
  echo "No V8 profile log generated."
fi

echo ""
echo "==> Method 2: clinic.js (if installed)..."
if command -v clinic &>/dev/null; then
  echo "Run: clinic flame -- node ${APP_FILE}"
  echo "Run: clinic doctor -- node ${APP_FILE}"
else
  echo "clinic.js not installed. Install with: npm install -g clinic"
fi

echo ""
echo "==> Method 3: Chrome DevTools profiling..."
echo "Run: node --inspect ${APP_FILE}"
echo "Open: chrome://inspect -> Performance tab -> Record"

FAQ

Discussion

Loading comments...

#!/bin/bash set -euo pipefail # Node.js CPU Profiling Script APP_FILE="${1:-app.js}" DURATION="${2:-30}" echo "==> Profiling ${APP_FILE} for ${DURATION} seconds..." # Clean up old profiles rm -f isolate-*.log profile.txt echo "==> Method 1: V8 --prof profiling..." timeout ${DURATION} node --prof "${APP_FILE}" 2>/dev/null || true if ls isolate-*.log 1>/dev/null 2>&1; then echo "==> Processing V8 profile log..." node --prof-process isolate-*.log > profile.txt echo "" echo "==> Profile Summary:" head -30 profile.txt echo "" echo "Full profile saved to: profile.txt" else echo "No V8 profile log generated." fi echo "" echo "==> Method 2: clinic.js (if installed)..." if command -v clinic &>/dev/null; then echo "Run: clinic flame -- node ${APP_FILE}" echo "Run: clinic doctor -- node ${APP_FILE}" else echo "clinic.js not installed. Install with: npm install -g clinic" fi echo "" echo "==> Method 3: Chrome DevTools profiling..." echo "Run: node --inspect ${APP_FILE}" echo "Open: chrome://inspect -> Performance tab -> Record"