npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@dnlup/doc

v5.0.3

Published

Get usage and health data about your Node.js process

Downloads

1,221

Readme

doc

npm version Tests Benchmarks codecov Known Vulnerabilities

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

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.

Class: doc.Sampler

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: 1000 Under the hood the package uses monitorEventLoopDelay to track the event loop delay.
    • 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-v18.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-v18.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

Resource usage metric instance.

sampler.resourceUsage

Resource usage metric instance.

sampler.eventLoopDelay

Event loop delay metric instance.

sampler.eventLoopUtilization

Event loop utilization metric instance.

sampler.gc

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. It computes this value using the mean of the Histogram instance.

eventLoopDelay.raw

  • <Histogram>

Exposes the Histogram instance.

eventLoopDelay.compute(raw)

  • raw <number> The raw value obtained using the Histogram API.
  • Returns <number> The computed delay value.

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

gcMetric.pause

It tracks the global activity of the garbage collector.

gcMetric.major

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

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

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

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 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.getPercentile(percentile)

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

Class: GCAggregatedEntry

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

new GCAggregatedEntry()

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

gcAggregatedEntry.flags

  • <object>

This object contains the various histograms of each flag.

gcAggregatedEntry.flags.no

gcAggregatedEntry.flags.constructRetained

gcAggregatedEntry.flags.forced

gcAggregatedEntry.flags.synchronousPhantomProcessing

gcAggregatedEntry.flags.allAvailableGarbage

gcAggregatedEntry.flags.allExternalMemory

gcAggregatedEntry.flags.scheduleIdle

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 |

Diagnostics Channel support

Node diagnostics channel are supported.

const diagnosticsChannel = require('diagnostics_channel')
const doc = require('@dnlup/doc)

diagnosticsChannel.subscribe(doc.constants.DOC_CHANNEL, s => {
  console.log('A new instance', s)
})

diagnosticsChannel.subscribe(doc.constants.DOC_SAMPLES_CHANNEL, s => {
  console.log('A new sample', s)
})

doc()

License

ISC