Security News
Supply Chain Attack Detected in @solana/web3.js Library
A supply chain attack has been detected in versions 1.95.6 and 1.95.7 of the popular @solana/web3.js library.
By Sarah Gooding - Dec 03, 2024
Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
@dnlup/doc
Advanced tools
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
- API
doc([options])- Class:
doc.Sampler - Class:
CpuMetric - Class:
ResourceUsageMetric - Class:
EventLoopDelayMetric - Class:
EventLoopUtilizationMetric - Class:
GCMetric gcMetric.pause- Class:
GCEntry - Class:
GCAggregatedEntrynew GCAggregatedEntry()gcAggregatedEntry.flagsgcAggregatedEntry.flags.nogcAggregatedEntry.flags.constructRetainedgcAggregatedEntry.flags.forcedgcAggregatedEntry.flags.synchronousPhantomProcessinggcAggregatedEntry.flags.allAvailableGarbagegcAggregatedEntry.flags.allExternalMemorygcAggregatedEntry.flags.scheduleIdle
doc.errors- Diagnostics Channel support
- 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.
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
- 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 eachsampleIntervalms asampleevent is emitted. Default:1000Under the hood the package usesmonitorEventLoopDelayto 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 optionsaggregate<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:falseflags<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).aggregatehas to betrueto enable this option. Default:trueon Node version12.17.0and newer.
eventLoopDelayOptions<Object>: Options to setupmonitorEventLoopDelay. 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:trueon Node version12.19.0and 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 theHistogramAPI.- 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 optionsaggregate<boolean>: SeegcOptions.aggregatein the Sampler options.flags<boolean>: SeegcOptions.flagsin the Sampler 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.
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.
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.
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.
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
FAQs
Get usage and health data about your Node.js process
The npm package @dnlup/doc receives a total of 280 weekly downloads. As such, @dnlup/doc popularity was classified as not popular.
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.
Package last updated on 02 Nov 2023
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.
Related posts
Research
Security News
Malicious npm Package Targets Solana Developers and Hijacks Funds
A malicious npm package targets Solana developers, rerouting funds in 2% of transactions to a hardcoded address.
By Socket Research Team - Dec 02, 2024
Security News
Research
Typosquatting Cryptographic Libraries: Malicious npm Packages Threaten Crypto Developers with Keylogging and Wallet Theft
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
By Kirill Boychenko - Nov 27, 2024