npm package: @snapshot-labs/snapshot-metrics
Description: `snapshot-metrics` is a npm package that handle the metrics export for Snapshot backend projects. It simplifies and standardizes the process of setting up the metrics endpoint for any snapshot services.
Latest version: 1.4.1

# Snapshot-metrics

`snapshot-metrics` is a npm package that handle the metrics export for Snapshot backend projects. 
It simplifies and standardizes the process of setting up the metrics endpoint for any snapshot services.


## Pre-requisites

- Express
- Node >= 16

## Install

Add it in your project with

```bash 
yarn add @snapshot-labs/snapshot-metrics
```

## Usage

Import it in your app after creating the express instance 

```js
import express from 'express';
import initMetrics from '@snapshot-labs/metrics';

const app = express();
initMetrics(app);
```

By default, it will create a new `/metrics` endpoint, with some nodejs and express metrics. 

## Custom metrics
  
The `initMetrics` function takes an optional `options` parameter with the following signature: 

```ts 
options?: {
  promBundleOptions?: promBundle.Opts;
  normalizedPath?: NormalizePathEntry[] | NormalizePathFn;
  whitelistedPath?: RegExp[];
  errorHandler?: (e: any) => void;
}
```

### promBundleOptions

The same object as https://github.com/jochen-schweizer/express-prom-bundle#options, to override the default option set by the lib.

### normalizedPath

Same as object as https://github.com/jochen-schweizer/express-prom-bundle#more-details-on-includepath-option

In case `promBundleOptions` is set, it will have priority over this option.

### whitelistedPath

An array of RegExp, to filter the HTTP requests tracked by the metrics.

In case `promBundleOptions` is set, it will have priority over this option.

### errorHandler

An error handler function, to handle error thrown by the pushgateway connection.

Default: `(e: any) => console.log(e)`

## Default metrics

The module export default metrics from [https://github.com/siimon/prom-client](prom-client) and [https://github.com/jochen-schweizer/express-prom-bundle](express-prom-bundle),
as well as some custom metrics tailored for the @snapshot-labs.

## Custom Metrics

The module export a `client` object, which is a prom-client instance. You can use it to create custom metrics.

```js 
  new client.Gauge({
    name: 'my_custom_metric',
    help: 'My custom metric',
    labelNames: ['my_label'],
  }).set({ my_label: 'my_value' }, 1);
```

See https://github.com/siimon/prom-client#custom-metrics

## Authentication

You can lock the `/metrics` behind authencation by setting the `METRICS_AUTHORIZATION` env variable.

You then need to use the `Authorization` header when polling the `/metrics` endpoint:

```bash
curl -X GET -H "Authorization: Bearer [METRICS_AUTHORIZATION]" http://localhost/metrics
```

## Pushgateway

You can push the metrics to a pushgateway by setting the `METRICS_PUSHGATEWAY_URL` and `METRICS_INSTANCE` env variable.

```bash
# Value to be used as prefix to the instance label of pushed metrics
METRICS_INSTANCE=snapshot.org
# URL of the pushgateway
METRICS_PUSHGATEWAY_URL=http://localhost:9091
# Job name to be added to the job label of pushed metrics
METRICS_JOB_NAME=prometheus # Default
```

The pushed metrics `instance` label will be set to the `process.env.METRICS_INSTANCE`, 
followed by `process.env.HOSTNAME`, in order to differentiate multiple 
servers/container running the same service. `HOSTNAME` should already be set
by most server.

If the pushgateway requires authentication, set the following env var:

```bash
# Basic auth user
METRICS_PUSHGATEWAY_USER=
# Basic auth password
METRICS_PUSHGATEWAY_PASSWORD=
```

## License

[MIT](LICENSE)