Node.js perf_hooks Module Guide

The perf_hooks module provides precise performance timing APIs similar to browser Performance APIs. Here's how to use it.

Basic Timing#

import { performance } from 'node:perf_hooks';

// Get high-resolution timestamp
const start = performance.now();

// Do work
for (let i = 0; i < 1000000; i++) {
  Math.sqrt(i);
}

const end = performance.now();
console.log(`Execution time: ${end - start}ms`);

// Time origin
console.log('Time origin:', performance.timeOrigin);
// Unix timestamp when Node.js started

Performance Marks and Measures#

import { performance } from 'node:perf_hooks';

// Create marks
performance.mark('start');

// Do work
await processData();

performance.mark('process-complete');

// More work
await saveResults();

performance.mark('end');

// Create measures between marks
performance.measure('processing', 'start', 'process-complete');
performance.measure('saving', 'process-complete', 'end');
performance.measure('total', 'start', 'end');

// Get measures
const measures = performance.getEntriesByType('measure');
measures.forEach((measure) => {
  console.log(`${measure.name}: ${measure.duration.toFixed(2)}ms`);
});

// Clear marks and measures
performance.clearMarks();
performance.clearMeasures();

PerformanceObserver#

import { PerformanceObserver, performance } from 'node:perf_hooks';

// Create observer
const obs = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  entries.forEach((entry) => {
    console.log(`${entry.name}: ${entry.duration.toFixed(2)}ms`);
  });
});

// Observe specific entry types
obs.observe({ entryTypes: ['measure', 'function'] });

// Make measurements
performance.mark('A');
await doWork();
performance.mark('B');
performance.measure('work', 'A', 'B');

// Disconnect when done
obs.disconnect();

Timing Functions#

import { performance } from 'node:perf_hooks';

// Wrap function for timing
const timedFn = performance.timerify(originalFunction);

// Observer for function timing
const obs = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  entries.forEach((entry) => {
    console.log(`Function ${entry.name} took ${entry.duration}ms`);
  });
});

obs.observe({ entryTypes: ['function'] });

// Call timed function
timedFn(arg1, arg2);

// Async function timing
async function timeAsync(fn, name) {
  const start = performance.now();
  try {
    return await fn();
  } finally {
    const duration = performance.now() - start;
    console.log(`${name}: ${duration.toFixed(2)}ms`);
  }
}

await timeAsync(() => fetchData(), 'fetchData');

HTTP Server Timing#

import http from 'node:http';
import { performance, PerformanceObserver } from 'node:perf_hooks';

// Track request timing
const requestTiming = new Map();

const server = http.createServer(async (req, res) => {
  const requestId = `${Date.now()}-${Math.random()}`;

  performance.mark(`${requestId}-start`);

  // Process request
  performance.mark(`${requestId}-before-db`);
  const data = await queryDatabase();
  performance.mark(`${requestId}-after-db`);

  performance.mark(`${requestId}-before-render`);
  const html = renderTemplate(data);
  performance.mark(`${requestId}-after-render`);

  res.end(html);

  performance.mark(`${requestId}-end`);

  // Measure phases
  performance.measure(
    `${requestId}-db`,
    `${requestId}-before-db`,
    `${requestId}-after-db`
  );
  performance.measure(
    `${requestId}-render`,
    `${requestId}-before-render`,
    `${requestId}-after-render`
  );
  performance.measure(
    `${requestId}-total`,
    `${requestId}-start`,
    `${requestId}-end`
  );
});

Histogram for Statistics#

import { createHistogram, performance } from 'node:perf_hooks';

// Create histogram for timing distribution
const histogram = createHistogram();

// Record timings
for (let i = 0; i < 1000; i++) {
  const start = performance.now();
  await doOperation();
  const duration = performance.now() - start;

  histogram.record(Math.floor(duration * 1000)); // microseconds
}

// Get statistics
console.log('Statistics:');
console.log('Min:', histogram.min / 1000, 'ms');
console.log('Max:', histogram.max / 1000, 'ms');
console.log('Mean:', histogram.mean / 1000, 'ms');
console.log('Stddev:', histogram.stddev / 1000, 'ms');
console.log('50th percentile:', histogram.percentile(50) / 1000, 'ms');
console.log('95th percentile:', histogram.percentile(95) / 1000, 'ms');
console.log('99th percentile:', histogram.percentile(99) / 1000, 'ms');

Resource Timing#

import { PerformanceObserver } from 'node:perf_hooks';

// Monitor garbage collection
const gcObserver = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  entries.forEach((entry) => {
    console.log(`GC ${entry.detail.kind}: ${entry.duration.toFixed(2)}ms`);
  });
});

gcObserver.observe({ entryTypes: ['gc'] });

// Monitor event loop
const eventLoopObserver = new PerformanceObserver((list) => {
  const entries = list.getEntries();
  entries.forEach((entry) => {
    if (entry.duration > 100) {
      console.warn(`Slow event loop: ${entry.duration.toFixed(2)}ms`);
    }
  });
});

// Note: 'function' entries show event loop utilization

Custom Performance Entries#

import { performance, PerformanceEntry } from 'node:perf_hooks';

// Custom timing class
class APICallTiming {
  constructor(endpoint) {
    this.endpoint = endpoint;
    this.markName = `api-${endpoint}-${Date.now()}`;
  }

  start() {
    performance.mark(`${this.markName}-start`);
  }

  end() {
    performance.mark(`${this.markName}-end`);
    performance.measure(
      `API: ${this.endpoint}`,
      `${this.markName}-start`,
      `${this.markName}-end`
    );
  }
}

// Usage
const timing = new APICallTiming('/users');
timing.start();
const response = await fetch('http://api.example.com/users');
timing.end();

Performance Timeline#

import { performance } from 'node:perf_hooks';

// Get all entries
const allEntries = performance.getEntries();
console.log('All entries:', allEntries.length);

// Get entries by type
const marks = performance.getEntriesByType('mark');
const measures = performance.getEntriesByType('measure');

// Get entries by name
const specificMeasure = performance.getEntriesByName('api-call');

// Clear specific entries
performance.clearMarks('myMark');
performance.clearMeasures('myMeasure');

// Clear all
performance.clearMarks();
performance.clearMeasures();

Profiling Middleware#

import { performance } from 'node:perf_hooks';

// Express middleware for timing
function timingMiddleware(req, res, next) {
  const requestId = `req-${Date.now()}`;
  req.timingId = requestId;

  performance.mark(`${requestId}-start`);

  // Track response time
  const originalEnd = res.end;
  res.end = function (...args) {
    performance.mark(`${requestId}-end`);
    performance.measure(
      `${req.method} ${req.path}`,
      `${requestId}-start`,
      `${requestId}-end`
    );

    // Add timing header
    const measure = performance.getEntriesByName(
      `${req.method} ${req.path}`
    )[0];
    if (measure) {
      res.setHeader('Server-Timing', `total;dur=${measure.duration}`);
    }

    return originalEnd.apply(this, args);
  };

  next();
}

// Middleware for specific operations
function dbTimingMiddleware(req, res, next) {
  const originalQuery = req.db.query;

  req.db.query = async function (...args) {
    const queryId = `query-${Date.now()}`;
    performance.mark(`${queryId}-start`);

    try {
      return await originalQuery.apply(this, args);
    } finally {
      performance.mark(`${queryId}-end`);
      performance.measure(`DB Query`, `${queryId}-start`, `${queryId}-end`);
    }
  };

  next();
}

Benchmark Utility#

import { performance } from 'node:perf_hooks';

async function benchmark(name, fn, iterations = 1000) {
  // Warmup
  for (let i = 0; i < 10; i++) {
    await fn();
  }

  const times = [];

  for (let i = 0; i < iterations; i++) {
    const start = performance.now();
    await fn();
    times.push(performance.now() - start);
  }

  times.sort((a, b) => a - b);

  const stats = {
    name,
    iterations,
    min: times[0],
    max: times[times.length - 1],
    mean: times.reduce((a, b) => a + b) / times.length,
    median: times[Math.floor(times.length / 2)],
    p95: times[Math.floor(times.length * 0.95)],
    p99: times[Math.floor(times.length * 0.99)],
  };

  console.log(`\n${name}:`);
  console.log(`  Min: ${stats.min.toFixed(3)}ms`);
  console.log(`  Max: ${stats.max.toFixed(3)}ms`);
  console.log(`  Mean: ${stats.mean.toFixed(3)}ms`);
  console.log(`  Median: ${stats.median.toFixed(3)}ms`);
  console.log(`  P95: ${stats.p95.toFixed(3)}ms`);
  console.log(`  P99: ${stats.p99.toFixed(3)}ms`);

  return stats;
}

// Usage
await benchmark('JSON parse', () => {
  JSON.parse('{"key": "value"}');
});

Best Practices#

Measurement:
✓ Use marks and measures
✓ Name entries descriptively
✓ Clear entries after collection
✓ Use PerformanceObserver for async

Accuracy:
✓ Warmup before benchmarking
✓ Multiple iterations
✓ Calculate percentiles
✓ Account for GC pauses

Production:
✓ Sample measurements
✓ Aggregate statistics
✓ Monitor percentiles (p95, p99)
✓ Set alerting thresholds

Avoid:
✗ Too many performance marks
✗ Forgetting to clear entries
✗ Blocking with analysis
✗ Ignoring outliers

The perf_hooks module provides powerful tools for precise performance measurement in Node.js. Use marks and measures for timing code sections, PerformanceObserver for async monitoring, and histograms for statistical analysis. Implement timing middleware for HTTP servers and build benchmark utilities for comparing implementations. Remember to clear entries to prevent memory growth and sample in production to minimize overhead.