@dnlup/doc

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 provided by Node itself. It is not coupled with any APM platform so you are free to use anything you want for that purpose. Its API is designed to let you access both computed and raw values, where possible.

• Installation * latest stable version * latest development version
• Usage - Enable/disable metrics collection * Garbage collection * Active handles
• API
  • doc([options])
  • Class: doc.Sampler
    • new doc.Sampler([options])
    • Event: 'sample'
    • sampler.start()
    • sampler.stop()
    • sampler.cpu
    • sampler.eventLoopDelay
    • sampler.eventLoopUtilization
    • sampler.gc
    • sampler.activeHandles
    • sampler.memory
  • Class: CpuMetric
    • cpuMetric.usage
    • cpuMetric.raw
  • Class: EventLoopDelayMetric
    • eventLoopDelay.computed
    • eventLoopDelay.raw
    • eventLoopDelay.compute(raw)
  • Class: EventLoopUtilizationMetric
    • eventLoopUtilization.raw
  • Class: GCMetric
    • gcMetric.major
    • gcMetric.minor
    • gcMetric.incremental
    • gcMetric.weakCb
  • Class: GCAggregatedEntry
    • gcAggregatedEntry.count
    • gcAggregatedEntry.total
    • gcAggregatedEntry.average
    • gcAggregatedEntry.flags
      • count
      • total
• Credits

Installation

latest stable version

$ npm i @dnlup/doc

latest development version

$ npm i @dnlup/doc@next

Usage

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

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)
  doStuffWithGarbageCollectionDuration(sampler.gc)
})

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)
  doStuffWithActiveHandles(sampler.activeHandles)
})

API

doc([options])

Create a new 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 on a regular interval. A Sampler instance is stateful so, on each tick, only the values of the last sample are available. The old ones are overwritten each time a new sample event is emited.

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

Event: 'sample'

Emitted every sampleInterval, it signals that new data has been sampled.

sampler.start()

Start collecting metrics.

sampler.stop()

Stop collecting metrics.

sampler.cpu

• <CpuMetric>

Cpu 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

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: EventLoopDelayMetric

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 this value is computed using the mean of the Histogram instance, otherwise a simple timer is used 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 method is meant to be used only on node versions that supports monitorEventLoopDelay. It allows to get computed values of the event loop delay from other values than the mean of the Histogram instance.

Class: EventLoopUtilizationMetric

Exposes raw values about the event loop utilization.

eventLoopUtilization.raw

• <object>

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

Class: GCMetric

Exposes the garbage collector activity only with computed values. The rolling average of each type of operation is calculated during the specified sampleInterval.

gcMetric.major

• <GCAggregatedEntry>

Activity of the operation of type major.

See performanceEntry.kind.

gcMetric.minor

• <GCAggregatedEntry>

Activity of the operation of type minor.

See performanceEntry.kind.

gcMetric.incremental

• <GCAggregatedEntry>

Activity of the operation of type incremental.

See performanceEntry.kind.

gcMetric.weakCb

• <GCAggregatedEntry>

Activity of the operation of type weakCb.

See performanceEntry.kind.

Class: GCAggregatedEntry

Entry containing 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 a specific flag was encountered 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'

See performanceEntry.flags.

Each value of the Map is an <object> with the following properties:

count

• <number>

The number of time that the flag was encountered.

total

• <number>

The total time (in milliseconds) spent on the operations with this flag.

Credits

When writing this module a lot of inspiration was taken from the awesome Node Clinic Doctor package.