doc

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 available on Node itself (no native dependencies). 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.

Installation * latest stable version * latest development version
Usage * Importing with CommonJS * Importing with ESM * Note - Enable/disable metrics collection - Garbage collection - Active handles
- Examples
API
License

Installation

latest stable version

$ npm i @dnlup/doc

latest development version

$ npm i @dnlup/doc@next

Usage

You can import the module by using either CommonJS or ESM.

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).

Importing with CommonJS

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.utilization) // Available only on Node versions that support it
})

Importing with ESM

import doc from '@dnlup/doc'

const sampler = doc()

sampler.on('sample', () => {
  doStuffWithCpuUsage(sampler.cpu.usage)
  doStuffWithMemoryUsage(sampler.memory)
  doStuffWithEventLoopDelay(sampler.eventLoopDelay.computed)
  doStuffWithEventLoopUtilization(sampler.eventLoopUtilization.utilization) // Available only on Node versions that support it
})

Note

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.

Enable/disable metrics collection

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)
  doStuffWithEventLoopUtilization(sampler.eventLoopUtilization.utilization) // Available only on Node versions that support it
})

You can enable more metrics if you need them.

Garbage collection

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)
  doStuffWithEventLoopUtilization(sampler.eventLoopUtilization.utilization) // Available only on Node versions that support it
  doStuffWithGarbageCollectionDuration(sampler.gc.pause)
})

Active handles

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)
  doStuffWithEventLoopUtilization(sampler.eventLoopUtilization.utilization) // Available only on Node versions that support it
  doStuffWithActiveHandles(sampler.activeHandles)
})

Examples

You can find more examples in the examples folder.

API

`doc([options])`

It creates a metrics Sampler instance with the given options.

options <Object>: same as the Sampler options.
Returns: <Sampler>

Class: `doc.Sampler`

Extends EventEmitter.

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.

new `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.
- gcOptions <Object>: Garbage collection options
  - aggregate <boolean>: Track and aggregate statistics about each garbage collection operation (see https://nodejs.org/docs/latest-v12.x/api/perf_hooks.html#perf_hooks_performanceentry_kind). Default: false
  - flags <boolean>: , Track statistics about the flags of each (aggregated) garbage collection operation (see https://nodejs.org/docs/latest-v12.x/api/perf_hooks.html#perf_hooks_performanceentry_flags). aggregate has to be true to enable this option. Default: true on Node version 12.17.0 and newer.
- eventLoopDelayOptions <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 version 12.19.0 and newer.
  - 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.

Event: '`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.cpu`

<CpuMetric>

Resource usage metric instance.

`sampler.resourceUsage`

<ResourceUsageMetric>

Resource usage metric instance.

`sampler.eventLoopDelay`

<EventLoopDelayMetric>

Event loop delay metric instance.

`sampler.eventLoopUtilization`

<EventLoopUtilizationMetric>

Event loop utilization metric instance.

`sampler.gc`

<GCMetric>

Garbage collector metric instance.

`sampler.activeHandles`

<number>

Number of active handles returned by process._getActiveHandles().

`sampler.memory`

<object>

Object returned by process.memoryUsage().

Class: `CpuMetric`

It 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().

Class: `ResourceUsageMetric`

It 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().

Class: `EventLoopDelayMetric`

It 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.
Returns <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.

Class: `EventLoopUtilizationMetric`

It exposes statistics about the event loop utilization.

`eventLoopUtilization.idle`

<number>

The idle value in the object returned by performance.eventLoopUtilization() during the sampleInterval window.

`eventLoopUtilization.active`

<number>

The active value in the object returned by performance.eventLoopUtilization() during the sampleInterval window.

`eventLoopUtilization.utilization`

<number>

The utilization value in the object returned by performance.eventLoopUtilization() during the sampleInterval window.

`eventLoopUtilization.raw`

<object>

Raw value returned by performance.eventLoopUtilization() during the sampleInterval window.

Class: `GCMetric`

It exposes the garbage collector activity statistics in the specified sampleInterval using hdr histograms.

`new GCMetric(options)`

options <object>: Configuration options
- aggregate <boolean>: See gcOptions.aggregate in the Sampler options.
- flags <boolean>: See gcOptions.flags in the Sampler options.

`gcMetric.pause`

<GCEntry>

It tracks the global activity of the garbage collector.

`gcMetric.major`

<GCEntry> | <GCAggregatedEntry>

The activity of the operation of type major. It's present only if GCMetric has been created with the option aggregate equal to true.

See performanceEntry.kind.

`gcMetric.minor`

<GCEntry> | <GCAggregatedEntry>

The activity of the operation of type minor. It's present only if GCMetric has been created with the option aggregate equal to true.

See performanceEntry.kind.

`gcMetric.incremental`

<GCEntry> | <GCAggregatedEntry>

The activity of the operation of type incremental. It's present only if GCMetric has been created with the option aggregate equal to true.

See performanceEntry.kind.

`gcMetric.weakCb`

<GCEntry> | <GCAggregatedEntry>

The activity of the operation of type weakCb. It's present only if GCMetric has been created with the option aggregate equal to true.

See performanceEntry.kind.

Class: `GCEntry`

It contains garbage collection data, represented with an hdr histogram. All timing values are expressed in nanoseconds.

`new GCEntry()`

The initialization doesn't require options. It is created internally by a GCMetric.

`gcEntry.totalDuration`

<number>

It is the total time of the entry in nanoseconds.

`gcEntry.totalCount`

<number>

It is the total number of operations counted.

`gcEntry.mean`

<number>

It is the mean value of the entry in nanoseconds.

`gcEntry.max`

<number>

It is the maximum value of the entry in nanoseconds.

`gcEntry.min`

<number>

It is the minimum value of the entry in nanoseconds.

`gcEntry.stdDeviation`

<number>

It is the standard deviation of the entry in nanoseconds.

`gcEntry.summary`

<object>

The hdr histogram summary. See https://github.com/HdrHistogram/HdrHistogramJS#record-values-and-retrieve-metrics.

`gcEntry.getPercentile(percentile)`

percentile <number>: Get a percentile from the histogram.
Returns <number> The percentile

See https://github.com/HdrHistogram/HdrHistogramJS#record-values-and-retrieve-metrics.

Class: `GCAggregatedEntry`

It extends GCEntry and contains garbage collection data plus the flags associated with it (see https://nodejs.org/docs/latest-v12.x/api/perf_hooks.html#perf_hooks_performanceentry_flags).

`new GCAggregatedEntry()`

The initialization doesn't require options. It is created internally by a GCMetric.

`gcAggregatedEntry.flags`

<object>

This object contains the various hdr histograms of each flag.

`doc.eventLoopUtilizationSupported`

<boolean>

It tells if the Node.js version in use supports the eventLoopUtilization metric.

`doc.resourceUsageSupported`

<boolean>

It tells if the Node.js version in use supports the resourceUsage metric.

`doc.gcFlagsSupported`

<boolean>

It tells if the Node.js version in use supports GC flags.

`doc.errors`

In the errors object are exported all the custom errors used by the module.

Error	Error Code	Description
`InvalidArgumentError`	`DOC_ERR_INVALID_ARG`	An invalid option or argument was used
`NotSupportedError`	`DOC_ERR_NOT_SUPPORTED`	A metric is not supported on the Node.js version used

License

ISC

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

dnlup / doc

Programming Languages

Labels

Projects that are alternatives of or similar to doc

doc

Installation

latest stable version

latest development version

Usage

Importing with CommonJS

Importing with ESM

Note

Enable/disable metrics collection

Garbage collection

Active handles

Examples

API

doc([options])

Class: doc.Sampler

new doc.Sampler([options])

Event: 'sample'

sampler.start()

sampler.stop()

sampler.cpu

sampler.resourceUsage

sampler.eventLoopDelay

sampler.eventLoopUtilization

sampler.gc

sampler.activeHandles

sampler.memory

Class: CpuMetric

cpuMetric.usage

cpuMetric.raw

Class: ResourceUsageMetric

resourceUsage.cpu

resourceUsage.raw

Class: EventLoopDelayMetric

eventLoopDelay.computed

eventLoopDelay.raw

eventLoopDelay.compute(raw)

Class: EventLoopUtilizationMetric

eventLoopUtilization.idle

eventLoopUtilization.active

eventLoopUtilization.utilization

eventLoopUtilization.raw

Class: GCMetric

new GCMetric(options)

gcMetric.pause

gcMetric.major

gcMetric.minor

gcMetric.incremental

gcMetric.weakCb

Class: GCEntry

new GCEntry()

gcEntry.totalDuration

gcEntry.totalCount

gcEntry.mean

gcEntry.max

gcEntry.min

gcEntry.stdDeviation

gcEntry.summary

gcEntry.getPercentile(percentile)

Class: GCAggregatedEntry

new GCAggregatedEntry()

gcAggregatedEntry.flags

gcAggregatedEntry.flags.no

gcAggregatedEntry.flags.constructRetained

gcAggregatedEntry.flags.forced

gcAggregatedEntry.flags.synchronousPhantomProcessing

gcAggregatedEntry.flags.allAvailableGarbage

gcAggregatedEntry.flags.allExternalMemory

gcAggregatedEntry.flags.scheduleIdle

doc.eventLoopUtilizationSupported

doc.resourceUsageSupported

doc.gcFlagsSupported

doc.errors

License

`doc([options])`

Class: `doc.Sampler`

new `doc.Sampler([options])`

Event: '`sample`'

`sampler.start()`

`sampler.stop()`

`sampler.cpu`

`sampler.resourceUsage`

`sampler.eventLoopDelay`

`sampler.eventLoopUtilization`

`sampler.gc`

`sampler.activeHandles`

`sampler.memory`

Class: `CpuMetric`

`cpuMetric.usage`

`cpuMetric.raw`

Class: `ResourceUsageMetric`

`resourceUsage.cpu`

`resourceUsage.raw`

Class: `EventLoopDelayMetric`

`eventLoopDelay.computed`

`eventLoopDelay.raw`

`eventLoopDelay.compute(raw)`

Class: `EventLoopUtilizationMetric`

`eventLoopUtilization.idle`

`eventLoopUtilization.active`

`eventLoopUtilization.utilization`

`eventLoopUtilization.raw`

Class: `GCMetric`

`new GCMetric(options)`

`gcMetric.pause`

`gcMetric.major`

`gcMetric.minor`

`gcMetric.incremental`

`gcMetric.weakCb`

Class: `GCEntry`

`new GCEntry()`

`gcEntry.totalDuration`

`gcEntry.totalCount`

`gcEntry.mean`

`gcEntry.max`

`gcEntry.min`

`gcEntry.stdDeviation`

`gcEntry.summary`

`gcEntry.getPercentile(percentile)`

Class: `GCAggregatedEntry`

`new GCAggregatedEntry()`

`gcAggregatedEntry.flags`

`gcAggregatedEntry.flags.no`

`gcAggregatedEntry.flags.constructRetained`

`gcAggregatedEntry.flags.forced`

`gcAggregatedEntry.flags.synchronousPhantomProcessing`

`gcAggregatedEntry.flags.allAvailableGarbage`

`gcAggregatedEntry.flags.allExternalMemory`

`gcAggregatedEntry.flags.scheduleIdle`

`doc.eventLoopUtilizationSupported`

`doc.resourceUsageSupported`

`doc.gcFlagsSupported`

`doc.errors`