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

yarn add @snapshot-labs/snapshot-metrics

Usage

Import it in your app after creating the express instance

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:

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 and https://github.com/jochen-schweizer/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.

  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:

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.

# 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:

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

License

MIT