# node-key-metrics

> Package for collecting metrics with Prometheus

Latest version **2.1.2** (published 2024-07-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install node-key-metrics
pnpm add node-key-metrics
yarn add node-key-metrics
bun add node-key-metrics
```

## Health

**Score 35/100 (D)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 2.1.2 |
| Published | 2024-07-16 |
| First published | 2023-06-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=16.0 |
| Dependencies | 2 |
| Unpacked size | 23.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 4 |
| Author | Ignat Ospadov |
| Maintainers | aror |
| Keywords | metrics, monitoring, node-metrics |

## Links

- npm: https://www.npmjs.com/package/node-key-metrics
- Repository: https://github.com/aror/node-metrics
- Homepage: https://github.com/aror/node-metrics#readme
- Issues: https://github.com/aror/node-metrics/issues
- npm.io page: https://npm.io/package/node-key-metrics

## Dependencies (2)

- [joi](https://npm.io/package/joi.md) ^17.9.2
- [prom-client](https://npm.io/package/prom-client.md) ^14.2.0

## Recent versions

- 2.1.2 (latest) — 2024-07-16
- 2.1.1 — 2024-07-16
- 2.1.0 — 2024-01-15
- 2.0.0 — 2023-10-12
- 1.0.2 — 2023-06-27
- 1.0.1 — 2023-06-26
- 1.0.0 — 2023-06-26

## README

# Metrics Library for Node.js

[![npm package][npm-img]][npm-url]
[![Downloads][downloads-img]][downloads-url]
[![Issues][issues-img]][issues-url]

## A simple, lightweight metrics library that provides an interface for instrumenting Node.js applications with Prometheus.

## Motivation

This library is a JavaScript port of the [metrics](https://github.com/rabellamy/metrics) package written in Go lang by [Tony Bellamy](https://github.com/rabellamy).

Observability is a crucial aspect of building scalable and reliable applications. Instrumenting applications to gather meaningful metrics is a challenging task, especially when teams are not familiar with the fundamental concepts and best practices. This library aims to address these challenges by providing a streamlined approach to instrumenting Node.js applications with Prometheus. It draws inspiration from proven strategies and methodologies, such as the **USE Method**, **RED Method**, and **The Four Golden Signals**.

The primary goals of this library are to:

- Provide **Minimal Viable Metrics (MVMs)** based on well-established strategies, allowing teams to bootstrap their instrumentation efforts.
- Simplify the process of creating Prometheus counters, gauges, histograms, and summaries.
- Foster the adoption of **Service Level Objectives (SLOs)** and proven instrumentation practices.

## Features

- Easy creation of Prometheus counters, gauges, histograms, and summaries.
- Implementation of **MVMs** based on the **USE Method**, **RED Method**, and **The Four Golden Signals**.

## Naming
- `RED` class represents the RED method which focuses on measuring:
  - **Rate** - the number of requests, per second, you services are serving
  - **Errors** - the number of failed requests per second
  - **Duration** - distributions of the amount of time each request takes
- `FourGoldenSignals` class represents **The Four Golden Signals** and focuses on measuring:
  - **Latency** - the time it takes to service a request
  - **Traffic** - how much demand is being placed on your system
  - **Errors** - rate of requests that fail
  - **Saturation** - measure of system consumption
- `USE` class represents the USE method which focuses on measuring:
  - **Errors** - count of error events
  - **Saturation** - the degree to which the resource has extra work which it can't service, often queued
  - **Utilization** - the average time that the resource was busy servicing work

## Usage

- Install the library
  - via NPM: `npm install node-key-metrics`
  - via yarn: `yarn add node-key-metrics`
- Import one of the MVM classes
```JavaScript
import { USE } from 'node-key-metrics'

// Create an instance of USE with the desired configuration
// The DefaultMetric can be either collected or disabled based on the value of the collectDefaultMetrics parameter. By default disabled.
const useMetrics = new USE({
  saturationName: 'saturation',
  saturationHelp: 'saturation metric help text',
  saturationLabels: ['label1', 'label2'],
  utilizationName: 'utilization',
  utilizationHelp: 'utilization metric help text',
  utilizationLabels: ['label3', 'label4'],
  collectDefaultMetrics: true,
})

// Increment the error counter
useMetrics.errors.inc()

// Set the saturation and utilization values
useMetrics.saturation.set({ label1: 'value1', label2: 'value2' }, 0.75)
useMetrics.utilization.set({ label3: 'value3', label4: 'value4' }, 0.5)
```

OR
- Use basic prometheus metrics:
```JavaScript
import { counter, defaultMetrics, gauge, histogram, summary } from 'node-key-metrics'

// Register default metrics collector
defaultMetrics()

// Create a counter metric
const errorCounter = counter({
  name: 'errors_total',
  help: 'number of errors',
  labelNames: ['error'],
})

// Increment the error counter
errorCounter.inc({ error: 'sample_error' })

// Create a gauge metric
const saturationGauge = gauge({
  name: 'saturation',
  help: 'saturation metric help text',
  labelNames: ['label1', 'label2'],
})

// Set the saturation value
saturationGauge.set({ label1: 'value1', label2: 'value2' }, 0.75)

// Create a histogram metric
const responseTimeHistogram = histogram({
  name: 'response_time',
  help: 'response time metric help text',
  labelNames: ['endpoint'],
})

// Observe a response time value
responseTimeHistogram.observe({ endpoint: '/api/some-endpoint' }, 100)

// Create a summary metric
const requestSizeSummary = summary({
  name: 'request_size',
  help: 'request size metric help text',
  labelNames: ['endpoint'],
})

// Observe a request size value
requestSizeSummary.observe({ endpoint: '/api/another-endpoint' }, 1024)
```
- to expose the metrics to prometheus, use the `collect` method:

```JavaScript
import { collect } from 'node-key-metrics'

app.get('/metrics', (req, res) => {
  res.set('Content-Type', 'text/plain')
  res.end(collect())
})

```

[downloads-img]:https://img.shields.io/npm/dt/typescript-npm-package-template
[downloads-url]:https://www.npmtrends.com/node-key-metrics
[npm-img]:https://img.shields.io/npm/v/typescript-npm-package-template
[npm-url]:https://www.npmjs.com/package/node-key-metrics
[issues-img]:https://img.shields.io/github/issues/ryansonshine/typescript-npm-package-template
[issues-url]:https://github.com/aror/node-key-metrics/issues

---
_Source: https://npm.io/package/node-key-metrics · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._