Skip to content

Commit

Permalink
docs: deduplicate reference documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@wkillerud
wkillerud authored Feb 19, 2024
1 parent 029bac7 commit 2e97b87
Showing 1 changed file with 7 additions and 316 deletions.
323 changes: 7 additions & 316 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,329 +2,20 @@

Module for collecting different process and system metrics providing them as a metric stream.

[![Dependencies](https://img.shields.io/david/metrics-js/process.svg)](https://david-dm.org/metrics-js/process)
[![GitHub Actions status](https://github.com/metrics-js/process/workflows/Run%20Lint%20and%20Tests/badge.svg)](https://github.com/metrics-js/process/actions?query=workflow%3A%22Run+Lint+and+Tests%22)
[![Known Vulnerabilities](https://snyk.io/test/github/metrics-js/process/badge.svg?targetFile=package.json)](https://snyk.io/test/github/metrics-js/process?targetFile=package.json)

## Installation
# @metrics/client

```bash
$ npm install @metrics/process
```
[![GitHub Actions status](https://github.com/metrics-js/client/workflows/Run%20Lint%20and%20Tests/badge.svg)](https://github.com/metrics-js/client/actions?query=workflow%3A%22Run+Lint+and+Tests%22)
[![Known Vulnerabilities](https://snyk.io/test/github/metrics-js/client/badge.svg?targetFile=package.json)](https://snyk.io/test/github/metrics-js/client?targetFile=package.json)

## Example
A streaming metric producer. Allows producing counters, gauges, time series in a way that is independent of your metrics system so that you can produce metrics and let consumers decide how to consume them. Additionally, you can pipe together different metrics streams before finally consuming them all in a single location.

```js
const stream = require('stream');
const Process = require('@metrics/process');

const proc = new Process();

proc.pipe(new stream.Writable({
objectMode: true,
write(chunk, encoding, callback) {
console.log(chunk);
callback();
},
}));

proc.start();
```

## Description

This module collects different process and system metrics on a scheduled frequency. The module is
a readable stream which each metrics is emitted on as an metric object on each schedule.

The stream of metrics can be piped into ex the [@metrics/client](https://github.com/metrics-js/client)
or the [@metrics/emitter](https://github.com/metrics-js/emitter) for further distribution.

Example:

```js
const Process = require('@metrics/process');
const Client = require('@metrics/client');
const Emitter = require('@metrics/emitter');

const proc = new Process();
const client = new Client();
const emitter = new Emitter('udp', { port: 45000 });

proc.pipe(client).pipe(emitter);

proc.start();
```

Each metric is collected by a collector. Most collectors will provide metrics on each scheduled
run or when the underlaying feature for generating the metric emits to build the metric out of,
but some metrics will only run once due to its nature. Some metrics will not be collected on
some operating systems. Please see [collectors](#collectors) for further detail.

### On not staying alive

The internal scheduler is a defered interval which prevents kicking off the collection of a new
set of metrics before any previous collection of metrics has finished. This prevents duplicate
metrics and possible memory leaks if any of the async operations of collecting the metrics get
stale for some weird reason.

The scheduler is by default [unrefered](https://nodejs.org/en/docs/guides/timers-in-node/) so
it will not hold up your node.js process.

## Constructor

Create a new Process instance.

```js
const Process = require('@metrics/process');
const proc = new Process(options);
```

### options (optional)

An Object containing misc configuration. The following values can be provided:

* **interval** - `Number` - Time between each collection of process metrics in milliseconds. Default: 10000ms.
* **prefix** - `String` - A prefix to be added to each metrics name.

### returns

Returns a Readable stream in object mode.

## API

The Process instance has the following API:

### .start(options)

Starts the scheduling of metric collection. The first run of metric collection will run immediately
upon calling this method.

### options (optional)

An Object containing misc configuration. The following values can be provided:

* **gc** - `Boolean` - Turns collection of gc metrics on or off. Default: false.

### .stop()

Stops the scheduling of metric collection. Calling this method will not break the stream pipeline.

## Events

An instance of the object will emit the following events:

### drop

Emitted when the process is dropping metrics. Will emit the dropped metric.

_Example_

```js
const process = new Process();
process.on('drop', metric => {
console.log('dropped metric', metric);
});
```

### collect:start

Emitted when the process starts collecting metrics.

_Example_

```js
const process = new Process();
process.on('collect:start', () => {
console.log('Started collecting metrics');
});
process.start();
```

### collect:end

Emitted when the process is done collecting metrics.

_Example_

```js
const process = new Process();
process.on('collect:end', () => {
console.log('Ended collecting metrics');
});
process.start();
```

## Collectors

These are the following mertics collected by this module:

### Version

The Version collector emits a metric with the node.js version used to run the process.

* **metric name:** nodejs_version_info
* **collected when:** Only once
* **collected on:** All operating systems

### V8 heap

The V8 Heap collector emits metrics about the V8 heap spaces.

Metric I:

* **metric name:** nodejs_heap_space_size_total_bytes
* **collected when:** On every collect
* **collected on:** All operating systems

Metric II:

* **metric name:** nodejs_heap_space_size_used_bytes
* **collected when:** On every collect
* **collected on:** All operating systems

Metric III:

* **metric name:** nodejs_heap_space_size_available_bytes
* **collected when:** On every collect
* **collected on:** All operating systems

### Process start time

The Process start time collector emits a metric for when the node.js process started.

* **metric name:** process_start_time_seconds
* **collected when:** Only once
* **collected on:** All operating systems

### Resident memory

The Resident memory collector emits metrics with resident memory in bytes, virtual
memory in bytes and process heap size in bytes.

Metric I:

* **metric name:** process_resident_memory_bytes
* **collected when:** On every collect
* **collected on:** All operating systems

Metric II:

* **metric name:** process_virtual_memory_bytes
* **collected when:** On every collect
* **collected on:** Linux only

Metric III:

* **metric name:** process_heap_bytes
* **collected when:** On every collect
* **collected on:** Linux only

### Open file descriptors

The Open file descriptor collector emits a metric with the number of open file
descriptors.

* **metric name:** process_open_fds
* **collected when:** On every collect
* **collected on:** Linux only

### Max file descriptors

The max file descriptor collector emits a metric with the maximum number of file
descriptors that can be opened.

* **metric name:** process_max_fds
* **collected when:** Only once
* **collected on:** Linux only

### Heap used and size

The Heap used and size collector emits metrics about the memory usage of the Node.js
process.

Metric I:

* **metric name:** nodejs_heap_size_total_bytes
* **collected when:** On every collect
* **collected on:** All operating systems

Metric II:

* **metric name:** nodejs_heap_size_used_bytes
* **collected when:** On every collect
* **collected on:** All operating systems

Metric III:

* **metric name:** nodejs_external_memory_bytes
* **collected when:** On every collect
* **collected on:** All operating systems

### Eventloop lag

The Eventloop lag collector emits a metric with the lag of the eventloop in seconds.

* **metric name:** nodejs_eventloop_lag_seconds
* **collected when:** On every collect
* **collected on:** All operating systems

### CPU total

The CPU total collector emits a metric with the user and system CPU time usage of the
current process. Values are in seconds.

Metric I:

* **metric name:** process_cpu_user_seconds_total
* **collected when:** On every collect
* **collected on:** All operating systems

Metric II:

* **metric name:** process_cpu_system_seconds_total
* **collected when:** On every collect
* **collected on:** All operating systems

Metric III:

* **metric name:** process_cpu_seconds_total
* **collected when:** On every collect
* **collected on:** All operating systems

### Active requests

The Active requests collector emits a metric with the number of open network requests
held by the node.js working queue.

* **metric name:** nodejs_active_requests_total
* **collected when:** On every collect
* **collected on:** All operating systems if `process._getActiveRequests()` is available

### Active handles

The Active handles collector emits a metric with the number of open handles (such as
`setTimeout` etc) held by the node.js working queue.

* **metric name:** nodejs_active_handles_total
* **collected when:** On every collect
* **collected on:** All operating systems if `process._getActiveRequests()` is available

### Garbage collection

The garbage collection (GC) collector emits a metric timing the length of the GC everytime
a GC has run.

Do note that collecting metrics on GC has a performance impact on the system in it self.
Its adviced that collecting GC metrics should be done in moderation and for small periods
of time.

Collecting GC metrics is by default turned off. It can be enabled by the `gc` argument on
the `.start()` method.

* **metric name:** nodejs_gc_duration_seconds
* **collected when:** When enabled, every time a GC is done
* **collected on:** All operating systems
## Usage

- [Getting started with MetricsJS](https://metrics-js.github.io/introduction/getting-started/).
- [Reference documentaiton for `@metrics/process`](https://metrics-js.github.io/reference/process/).

## Attribution

Expand Down

0 comments on commit 2e97b87

Please sign in to comment.