@dnlup/doc
Advanced tools
Get usage and health data about your Node.js process.
doc is a small module that helps you collect health metrics about your Node.js process.
It does that by using only the API provided available on Node itself.
It doesn't have any ties with an APM platform, so you are free to use anything you want for that purpose.
Its API lets you access both computed and raw values, where possible.
$ npm i @dnlup/doc
$ npm i @dnlup/doc@next
By default doc returns a Sampler instance that collects metrics about cpu, memory usage, event loop delay and event loop utilization (only on Node versions that support it).
const doc = require('@dnlup/doc');
const sampler = doc(); // Use the default options
sampler.on('sample', () => {
doStuffWithCpuUsage(sampler.cpu.usage)
doStuffWithMemoryUsage(sampler.memory)
doStuffWithEventLoopDelay(sampler.eventLoopDelay.computed)
doStuffWithEventLoopUtilization(sampler.eventLoopUtilization.raw) // Available only on Node versions that support it
})
A Sampler holds a snapshot of the metrics taken at the specified sample interval.
This behavior makes the instance stateful. On every tick, a new snapshot will overwrite the previous one.
You can disable the metrics that you don't need.
const doc = require('@dnlup/doc')
// Collect only the event loop delay
const sampler = doc({ collect: { cpu: false, memory: false } })
sampler.on('sample', () => {
// `sampler.cpu` will be `undefined`
// `sampler.memory` will be `undefined`
doStuffWithEventLoopDelay(sampler.eventLoopDelay.computed)
})
You can enable more metrics if you need them.
const doc = require('@dnlup/doc');
const sampler = doc({ collect: { gc: true } })
sampler.on('sample', () => {
doStuffWithCpuUsage(sampler.cpu.usage)
doStuffWithMemoryUsage(sampler.memory)
doStuffWithEventLoopDelay(sampler.eventLoopDelay.computed)
doStuffWithGarbageCollectionDuration(sampler.gc)
})
const doc = require('@dnlup/doc')
const sampler = doc({ collect: { activeHandles: true } })
sampler.on('sample', () => {
doStuffWithCpuUsage(sampler.cpu.usage)
doStuffWithMemoryUsage(sampler.memory)
doStuffWithEventLoopDelay(sampler.eventLoopDelay.computed)
doStuffWithActiveHandles(sampler.activeHandles)
})
It creates a metrics Sampler instance with the given options.
doc.SamplerEventEmitter.Metrics sampler.
It collects the selected metrics at a regular interval. A Sampler instance is stateful so, on each tick,
only the values of the last sample are available. Each time the sampler emits the sample event, it will overwrite the previous one.
doc.Sampler([options])options <Object>
sampleInterval <number>: sample interval (ms) to get a sample. On each sampleInterval ms a sample event is emitted. Default: 500 on Node < 11.10.0, 1000 otherwise. Under the hood the package uses monitorEventLoopDelay when available to track the event loop delay and this allows to increase the default sampleInterval.autoStart <boolean>: start automatically to collect metrics. Default: true.unref <boolean>: unref the timer used to schedule the sampling interval. Default: true.eventLoopOptions <Object>: Options to setup monitorEventLoopDelay. Default: { resolution: 10 }collect <Object>: enable/disable the collection of specific metrics.
cpu <boolean>: enable cpu metric. Default: true.resourceUsage <boolean>: enable resourceUsage metric. Default: false.eventLoopDelay <boolean>: enable eventLoopDelay metric. Default: true.eventLoopUtilization <boolean>: enable eventLoopUtilization metric. Default: true on Node versions that support it.memory <boolean>: enable memory metric. Default: true.gc <boolean>: enable garbage collection metric. Default: false.activeHandles <boolean>: enable active handles collection metric. Default: false.If options.collect.resourceUsage is set to true, options.collect.cpu will be set to false because the cpu metric is already available in the resource usage metric.
sample'Emitted every sampleInterval, it signals that new data the sampler has collected new data.
sampler.start()Start collecting metrics.
sampler.stop()Stop collecting metrics.
sampler.cpuResource usage metric instance.
sampler.resourceUsageResource usage metric instance.
sampler.eventLoopDelayEvent loop delay metric instance.
sampler.eventLoopUtilizationEvent loop utilization metric instance.
sampler.gcGarbage collector metric instance.
sampler.activeHandles<number>Number of active handles returned by process._getActiveHandles().
sampler.memory<object>Object returned by process.memoryUsage().
CpuMetricIt exposes both computed and raw values of the cpu usage.
cpuMetric.usage<number>Cpu usage in percentage.
cpuMetric.raw<object>Raw value returned by process.cpuUsage().
ResourceUsageMetricIt exposes both computed and raw values of the process resource usage.
resourceUsage.cpu<number>Cpu usage in percentage.
resourceUsage.raw<object>Raw value returned by process.resourceUsage().
EventLoopDelayMetricIt exposes both computed and raw values about the event loop delay.
eventLoopDelay.computed<number>Event loop delay in milliseconds. On Node versions that support monitorEventLoopDelay, it computes this value using the mean of the Histogram instance. Otherwise, it uses a simple timer to calculate it.
eventLoopDelay.raw<Histogram|number>On Node versions that support monitorEventLoopDelay this exposes the Histogram instance. Otherwise, it exposes the raw delay value in nanoseconds.
eventLoopDelay.compute(raw)raw <number> The raw value obtained using the Histogram API.<number> The computed delay value.This function works only on node versions that support monitorEventLoopDelay. It allows to get computed values of the event loop delay from statistics other than the mean of the Histogram instance.
EventLoopUtilizationMetricIt exposes raw values about the event loop utilization.
eventLoopUtilization.raw<object>Raw value returned by performance.eventLoopUtilization() during the sampleInterval window.
GCMetricIt exposes the garbage collector activity only with computed values. It calculates the rolling average of each type of operation during the specified sampleInterval.
gcMetric.majorThe activity of the operation of type major.
gcMetric.minorThe activity of the operation of type minor.
gcMetric.incrementalThe activity of the operation of type incremental.
gcMetric.weakCbThe activity of the operation of type weakCb.
GCAggregatedEntryIt contains aggregated data about a specific garbage collector operation.
gcAggregatedEntry.count<number>The number of times the operation occurred.
gcAggregatedEntry.total<number>The total time (in milliseconds) spent on the operation.
gcAggregatedEntry.average<number>The average time (in milliseconds) spent each time in the operation.
gcAggregatedEntry.flags<Map>On Node versions that support flags this Map is populated with additional metrics about the number of times it encounters a specific flag and the total time (in milliseconds) spent on the operation with this flag.
Each key of the Map is one of these strings:
'no''constructRetained''forced''synchronousPhantomProcessing''allAvailableGarbage''allExternalMemory''scheduleIdle'Each value of the Map is an <object> with the following properties:
count<number>The number of times that it has encountered the flag.
total<number>The total time (in milliseconds) spent on the operations with this flag.
You found a bug or want to discuss and implement a new feature? This project welcomes contributions.
The code follows the standardjs style guide.
Every contribution should pass the existing tests or implementing new ones if that's the case.
# Run tests locally
$ npm test
# Run js tests
$ npm test:js
# Run typescript types tests
$ npm test:ts
# Lint all the code
$ npm lint
# Lint only js files
$ npm lint:js
# Lint only typescript files
$ npm lint:ts
# Create the TOC in the README
$ npm run doc
When writing this module, I took a lot of inspiration from the fantastic Node Clinic Doctor package.
FAQs
Get usage and health data about your Node.js process
We found that @dnlup/doc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.