dnlup · dnlup · Mar 26, 2021 · May 6, 2021
diff --git a/README.md b/README.md
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,124 @@
+# doc
+
+[![npm version](https://badge.fury.io/js/%40dnlup%2Fdoc.svg)](https://badge.fury.io/js/%40dnlup%2Fdoc)
+
+> 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
+
+```bash
+npm i @dnlup/doc
+```
+
+###### latest development version
+
+```bash
+npm i @dnlup/doc@next
+```
+
+## Usage
+
+You can import the module by using either CommonJS or ESM.
+
+By default `doc` returns a [`Sampler`](#class-docsampler) instance that collects metrics about cpu, memory usage, event loop delay and event loop utilization (only on Node versions that [support it](https://nodejs.org/docs/latest-v12.x/api/perf_hooks.html#perf_hooks_performance_eventlooputilization_utilization1_utilization2)).
+
+###### Importing with CommonJS
+
+```js
+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
+
+```js
+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.
+
+```js
+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
+
+```js
+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
+
+```js
+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`](https://github.com/dnlup/doc/tree/HEAD/examples) folder.
+
+## License
+
+[ISC](https://github.com/dnlup/doc/tree/HEAD/LICENSE)
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -0,0 +1,9 @@
+* [Home](/ "@dnlup/doc")
+* API
+  * [doc](/api/doc.md)
+  * [Sampler](/api/sampler.md)
+  * [CPUMetric](/api/cpu.md)
+  * [EventLoopDelayMetric](/api/eventloopdelay.md)
+  * [EventLoopUtilizationMetric](/api/eventlooputilization.md)
+  * [GCMetric](/api/gc.md)
+  * [ResourceUsageMetric](/api/resourceusage.md)
diff --git a/docs/api/cpu.md b/docs/api/cpu.md
@@ -0,0 +1,15 @@
+# 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()`](https://nodejs.org/dist/latest-v12.x/docs/api/process.html#process_process_cpuusage_previousvalue).
diff --git a/docs/api/doc.md b/docs/api/doc.md
@@ -0,0 +1,37 @@
+# `doc([options])`
+
+It creates a metrics [`Sampler`](#class-docsampler) instance with the given options.
+
+* `options` `<Object>`: same as the `Sampler` [`options`](/api/sampler.md#new-sampleroptions).
+* Returns: [`<Sampler>`](#class-docsampler)
+
+## `doc.Sampler`
+
+* [`Sampler`](/api/sampler.md)
+
+## `doc.eventLoopUtilizationSupported`
+
+* `<boolean>`
+
+It tells if the Node.js version in use supports the [eventLoopUtilization metric](https://nodejs.org/dist/latest-v12.x/docs/api/perf_hooks.html#perf_hooks_performance_eventlooputilization_utilization1_utilization2).
+
+## `doc.resourceUsageSupported`
+
+* `<boolean>`
+
+It tells if the Node.js version in use supports the [resourceUsage metric](https://nodejs.org/dist/latest-v12.x/docs/api/process.html#process_process_resourceusage).
+
+## `doc.gcFlagsSupported`
+
+* `<boolean>`
+
+It tells if the Node.js version in use supports [GC flags](https://nodejs.org/dist/latest-v12.x/docs/api/perf_hooks.html#perf_hooks_performanceentry_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 |
diff --git a/docs/api/eventloopdelay.md b/docs/api/eventloopdelay.md
@@ -0,0 +1,23 @@
+# 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`](https://nodejs.org/dist/latest-v13.x/docs/api/perf_hooks.html#perf_hooks_perf_hooks_monitoreventloopdelay_options), it computes this value using the `mean` of the [`Histogram`](https://nodejs.org/dist/latest-v12.x/docs/api/perf_hooks.html#perf_hooks_class_histogram) instance. Otherwise, it uses a simple timer to calculate it.
+
+## `eventLoopDelay.raw`
+
+* [`<Histogram>`](https://nodejs.org/dist/latest-v12.x/docs/api/perf_hooks.html#perf_hooks_class_histogram) | `<number>`
+
+On Node versions that support [`monitorEventLoopDelay`](https://nodejs.org/dist/latest-v12.x/docs/api/perf_hooks.html#perf_hooks_perf_hooks_monitoreventloopdelay_options) this exposes the [`Histogram`](https://nodejs.org/dist/latest-v12.x/docs/api/perf_hooks.html#perf_hooks_class_histogram) instance. Otherwise, it exposes the raw delay value in nanoseconds.
+
+## `eventLoopDelay.compute(raw)`
+
+* `raw` `<number>` The raw value obtained using the [`Histogram`](https://nodejs.org/dist/latest-v12.x/docs/api/perf_hooks.html#perf_hooks_class_histogram) API.
+* Returns `<number>` The computed delay value.
+
+This function works only on node versions that support [`monitorEventLoopDelay`](https://nodejs.org/dist/latest-v12.x/docs/api/perf_hooks.html#perf_hooks_perf_hooks_monitoreventloopdelay_options). It allows to get computed values of the event loop delay from statistics other than the `mean` of the [`Histogram`](https://nodejs.org/dist/latest-v12.x/docs/api/perf_hooks.html#perf_hooks_class_histogram) instance.
+
diff --git a/docs/api/eventlooputilization.md b/docs/api/eventlooputilization.md
@@ -0,0 +1,26 @@
+# Class: `EventLoopUtilizationMetric`
+
+It exposes statistics about the event loop utilization.
+
+#### `eventLoopUtilization.idle`
+
+* `<number>`
+
+The `idle` value in the object returned by [`performance.eventLoopUtilization()`](https://nodejs.org/docs/latest-v12.x/api/perf_hooks.html#perf_hooks_performance_eventlooputilization_utilization1_utilization2) during the `sampleInterval` window.
+
+## `eventLoopUtilization.active`
+
+* `<number>`
+
+The `active` value in the object returned by [`performance.eventLoopUtilization()`](https://nodejs.org/docs/latest-v12.x/api/perf_hooks.html#perf_hooks_performance_eventlooputilization_utilization1_utilization2) during the `sampleInterval` window.
+## `eventLoopUtilization.utilization`
+
+* `<number>`
+
+The `utilization` value in the object returned by [`performance.eventLoopUtilization()`](https://nodejs.org/docs/latest-v12.x/api/perf_hooks.html#perf_hooks_performance_eventlooputilization_utilization1_utilization2) during the `sampleInterval` window.
+
+## `eventLoopUtilization.raw`
+
+* `<object>`
+
+Raw value returned by [`performance.eventLoopUtilization()`](https://nodejs.org/docs/latest-v12.x/api/perf_hooks.html#perf_hooks_performance_eventlooputilization_utilization1_utilization2) during the `sampleInterval` window.
diff --git a/docs/api/gc.md b/docs/api/gc.md
@@ -0,0 +1,150 @@
+# 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](#new-docsampleroptions).
+  * `flags` `<boolean>`: See `gcOptions.flags` in the [Sampler options](#new-docsampleroptions).
+
+## `gcMetric.pause`
+
+* [`<GCEntry>`](#class-gcentry)
+
+It tracks the global activity of the garbage collector.
+
+## `gcMetric.major`
+
+* [`<GCEntry>`](#class-gcentry) | [`<GCAggregatedEntry>`](#class-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`](https://nodejs.org/dist/latest-v12.x/docs/api/perf_hooks.html#perf_hooks_performanceentry_kind).
+
+## `gcMetric.minor`
+
+* [`<GCEntry>`](#class-gcentry) | [`<GCAggregatedEntry>`](#class-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`](https://nodejs.org/dist/latest-v12.x/docs/api/perf_hooks.html#perf_hooks_performanceentry_kind).
+
+## `gcMetric.incremental`
+
+* [`<GCEntry>`](#class-gcentry) | [`<GCAggregatedEntry>`](#class-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`](https://nodejs.org/dist/latest-v12.x/docs/api/perf_hooks.html#perf_hooks_performanceentry_kind).
+
+## `gcMetric.weakCb`
+
+* [`<GCEntry>`](#class-gcentry) | [`<GCAggregatedEntry>`](#class-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`](https://nodejs.org/dist/latest-v12.x/docs/api/perf_hooks.html#perf_hooks_performanceentry_kind).
+
+# Class: `GCEntry`
+
+It contains garbage collection data, represented with an [hdr histogram](https://github.com/HdrHistogram/HdrHistogramJS). All timing values are expressed in nanoseconds.
+
+## `new GCEntry()`
+
+The initialization doesn't require options. It is created internally by a [`GCMetric`](#class-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`](#class-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`](#class-gcmetric).
+
+## `gcAggregatedEntry.flags`
+
+* `<object>`
+
+This object contains the various hdr histograms of each flag.
+
+## `gcAggregatedEntry.flags.no`
+
+* [`<GCEntry>`](#class-gcentry)
+
+## `gcAggregatedEntry.flags.constructRetained`
+
+* [`<GCEntry>`](#class-gcentry)
+
+
+## `gcAggregatedEntry.flags.forced`
+
+* [`<GCEntry>`](#class-gcentry)
+
+
+## `gcAggregatedEntry.flags.synchronousPhantomProcessing`
+
+* [`<GCEntry>`](#class-gcentry)
+
+
+## `gcAggregatedEntry.flags.allAvailableGarbage`
+
+* [`<GCEntry>`](#class-gcentry)
+
+
+## `gcAggregatedEntry.flags.allExternalMemory`
+
+* [`<GCEntry>`](#class-gcentry)
+
+## `gcAggregatedEntry.flags.scheduleIdle`
+
+* [`<GCEntry>`](#class-gcentry)