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.noderepository and is built and tested there. The public Profilers page currently marks the Node.js agent as coming soon;@reignite/profileris 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
- Start conservative and tune thresholds from observed behavior.
- Use cooldowns of 300–600 seconds.
- Cap
maxDumpsandmaxTraces. - Use CPU profiles for CPU issues and allocation profiles for suspected leaks.
- Use
StartDelaySecsto 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. |