Table of Contents

Profiler for Node.js

The Node.js agent monitors heap usage, CPU and event-loop delay in-process. When a configured threshold is exceeded it captures a heap snapshot, a CPU profile or an allocation profile.

Publication status. The Node.js agent lives in the profiler.node repository and is built and tested there. The public Profilers page currently marks the Node.js agent as coming soon; @reignite/profiler is the intended package name.

Install

npm install @reignite/profiler

The package includes v8-profiler-next, so heap snapshots and CPU/allocation profiles work without an extra native dependency.

Configure

Create profiler.config.json from the configuration block in the portal:

{
  "Performance": {
    "Profiler": {
      "ProfilerID": "your-profiler-id",
      "Environment": "Production",
      "KeyID": "your-key-id",
      "Secret": "your-secret",
      "Disabled": false,
      "StartDelaySecs": 60
    },
    "CollectionOptions": {
      "dumpPath": "./diagnostics/dumps",
      "tracePath": "./diagnostics/traces",
      "maxDumps": 10,
      "maxTraces": 10
    },
    "EventSourceActions": [
      {
        "DisplayName": "memory-heap-used",
        "Operator": ">",
        "Threshold": 500,
        "Trace": true,
        "TraceProfile": "allocation-sampling",
        "TraceTriggerType": "Memory",
        "Dump": true,
        "Cooldown": 300
      },
      {
        "DisplayName": "event-loop-delay",
        "Operator": ">",
        "Threshold": 100,
        "Trace": true,
        "TraceProfile": "cpu-sampling",
        "TraceTriggerType": "CPU",
        "Dump": false,
        "Cooldown": 180
      }
    ]
  }
}

The configuration loader normalizes PascalCase (the portal's format) to camelCase, so either spelling works.

Integrate

const { ReigniteProfiler } = require('@reignite/profiler');

async function startApp() {
  const profiler = new ReigniteProfiler();
  await profiler.initialize('./profiler.config.json');

  profiler.on('dump-collected', result =>
    console.log(`Heap snapshot: ${result.filePath}`));
  profiler.on('trace-collected', result =>
    console.log(`Trace: ${result.filePath}`));

  await profiler.start();

  runApplication();
}

startApp();

Metrics

Metric Unit
memory-usage MB
memory-heap-used, memory-heap-total, memory-external, memory-rss MB
cpu-user, cpu-system ms
event-loop-delay ms
active-handles, active-requests count
heap-space-used, heap-space-available MB

Collected artifacts

  • Heap snapshots (.heapsnapshot) — open them in Chrome DevTools → Memory → Load.
  • CPU profiles (.cpuprofile) — open them in Chrome DevTools → JavaScript Profiler → Load.
  • Allocation profiles (.heapprofile) — open them in Chrome DevTools → Memory → Load.

Best practices

  1. Start conservative and tune thresholds from observed behavior.
  2. Use cooldowns of 300–600 seconds.
  3. Cap maxDumps and maxTraces.
  4. Use CPU profiles for CPU issues and allocation profiles for suspected leaks.
  5. Use StartDelaySecs to skip startup noise.

Troubleshooting

Symptom Check
No artifact is produced The metric never crossed the threshold, or Trace/Dump is false for the action.
Authentication failure ProfilerID, KeyID, Secret or Environment does not match the portal.
Event-loop delay appears only under load That is the metric doing its job; tune the threshold rather than removing the action.
Native module install fails Confirm the Node.js version is supported by v8-profiler-next and that build tools are available.