Node.js Monitoring Guide: Performance Metrics, APM & Alerts (2026)

# Install
npm install prom-client

# src/metrics.ts
import { Registry, collectDefaultMetrics, Histogram, Counter, Gauge } from 'prom-client';

export const registry = new Registry();

// Automatically collects: heap, GC, event loop lag, active handles, CPU
collectDefaultMetrics({ register: registry, prefix: 'nodejs_' });

// Custom metrics
export const httpRequestDuration = new Histogram({
  name: 'http_request_duration_seconds',
  help: 'HTTP request duration in seconds',
  labelNames: ['method', 'route', 'status_code'],
  buckets: [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2, 5],
  registers: [registry],
});

export const httpRequestTotal = new Counter({
  name: 'http_requests_total',
  help: 'Total HTTP requests',
  labelNames: ['method', 'route', 'status_code'],
  registers: [registry],
});

// Expose /metrics endpoint
app.get('/metrics', async (req, res) => {
  res.set('Content-Type', registry.contentType);
  res.end(await registry.metrics());
});

# Install
npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node
npm install @opentelemetry/exporter-otlp-http

# src/instrumentation.ts (load BEFORE any other imports)
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-otlp-http';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-express': { enabled: true },
      '@opentelemetry/instrumentation-pg': { enabled: true },
      '@opentelemetry/instrumentation-redis': { enabled: true },
      '@opentelemetry/instrumentation-http': { enabled: true },
    }),
  ],
});

sdk.start();

# package.json — load instrumentation before app
{
  "scripts": {
    "start": "node --require ./dist/instrumentation.js dist/server.js"
  }
}

# Step 1: Take heap snapshots on demand (no downtime)
# Add to your app:
import { writeHeapSnapshot } from 'v8';

process.on('SIGUSR2', () => {
  const filename = writeHeapSnapshot();
  console.log('Heap snapshot written to', filename);
});

# Trigger from shell:
kill -USR2 <node-pid>

# Step 2: Open snapshot in Chrome DevTools
# chrome://inspect → Open dedicated DevTools for Node
# Memory tab → Load .heapsnapshot file
# Sort by "Retained Size" to find growing object types

# Step 3: Common leak patterns to search for:
# - EventEmitter listeners (MaxListenersExceededWarning)
# - Interval/timeout never cleared (setInterval without clearInterval)
# - Large arrays appended to module-level variables
# - Closure holding references to large objects

# Prometheus alert rules for Node.js
groups:
  - name: nodejs
    rules:
      # Event loop blocked
      - alert: NodeJSEventLoopLagHigh
        expr: nodejs_eventloop_lag_seconds > 0.1
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "Node.js event loop lag > 100ms"
          description: "CPU-bound work may be blocking the event loop"

      # Memory leak signal
      - alert: NodeJSHeapGrowth
        expr: |
          (nodejs_heap_size_used_bytes - nodejs_heap_size_used_bytes offset 30m)
          / nodejs_heap_size_used_bytes offset 30m > 0.2
        for: 30m
        labels:
          severity: warning
        annotations:
          summary: "Node.js heap grew >20% in 30 minutes"

      # Near OOM
      - alert: NodeJSHeapCritical
        expr: |
          nodejs_heap_size_used_bytes / nodejs_heap_size_total_bytes > 0.85
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Node.js heap >85% full — OOM crash imminent"

      # Process restart (tracks process uptime drops)
      - alert: NodeJSProcessRestarted
        expr: changes(nodejs_process_start_time_seconds[5m]) > 0
        labels:
          severity: warning
        annotations:
          summary: "Node.js process restarted"

      # High error rate
      - alert: NodeJSHighErrorRate
        expr: |
          rate(http_requests_total{status_code=~"5.."}[5m]) /
          rate(http_requests_total[5m]) > 0.01
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Node.js HTTP 5xx rate > 1%"