# Prometheus API Monitoring [![NPM Version][npm-image]][npm-url] [![NPM Downloads][downloads-image]][downloads-url] [![Build Status][travis-image]][travis-url] [![Test Coverage][coveralls-image]][coveralls-url] [![Known Vulnerabilities][snyk-image]][snyk-url] [![Apache 2.0 License][license-image]][license-url] - [Goal](#goal) - [Features](#features) - [Usage](#usage) - [Options](#options) - [Access the metrics](#access-the-metrics) - [Custom Metrics](#custom-metrics) - [Note](#note) - [Request.js HTTP request duration collector](#requestjs-http-request-duration-collector) - [Usage](#usage-1) - [request](#request) - [request-promise-native](#request-promise-native) - [axios](#axios) - [Test](#test) - [Usage in koa](#usage-in-koa) - [Prometheus Examples Queries](#prometheus-examples-queries) ## Goal API and process monitoring with [Prometheus](https://prometheus.io) for Node.js micro-service **Note: Prometheus (`prom-client`) is a peer dependency since 1.x version** ## Features - [Collect API metrics for each call](#usage) - Response time in seconds - Request size in bytes - Response size in bytes - Add prefix to metrics names - custom or project name - Exclude specific routes from being collect - Number of open connections to the server - Process Metrics as recommended by Prometheus [itself](https://prometheus.io/docs/instrumenting/writing_clientlibs/#standard-and-runtime-collectors) - Endpoint to retrieve the metrics - used for Prometheus scraping - Prometheus format - JSON format (`${path}.json`) - Support custom metrics - [Http function to collect request.js HTTP request duration](#requestjs-http-request-duration-collector) ## Usage ```js const apiMetrics = require('prometheus-api-metrics'); app.use(apiMetrics()) ``` ### Options | Option | Type | Description | Default Value | |--------------------------|-----------|-------------|---------------| | `metricsPath` | `String` | Path to access the metrics | `/metrics` | | `defaultMetricsInterval` | `Number` | Interval to collect the process metrics in milliseconds | `10000` | | `durationBuckets` | `Array` | Buckets for response time in seconds | `[0.001, 0.005, 0.015, 0.05, 0.1, 0.2, 0.3, 0.4, 0.5]` | | `requestSizeBuckets` | `Array` | Buckets for request size in bytes | `[5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000]` | | `responseSizeBuckets` | `Array` | Buckets for response size in bytes | `[5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000]` | | `useUniqueHistogramName` | `Boolean` | Add to metrics names the project name as a prefix (from package.json) | `false` | | `metricsPrefix` | `String` | A custom metrics names prefix, the package will add underscore between your prefix to the metric name | | | `excludeRoutes` | `Array` | Array of routes to exclude. Routes should be in your framework syntax | | | `includeQueryParams` | `Boolean` | Indicate if to include query params in route, the query parameters will be sorted in order to eliminate the number of unique labels | `false` | | `additionalLabels` | `Array` | Indicating custom labels that can be included on each `http_*` metric. Use in conjunction with `extractAdditionalLabelValuesFn`. | | `extractAdditionalLabelValuesFn` | `Function` | A function that can be use to generate the value of custom labels for each of the `http_*` metrics. When using koa, the function takes `ctx`, when using express, it takes `req, res` as arguments | | ### Access the metrics To get the metrics in Prometheus format use: ```sh curl http[s]://:[port]/metrics ``` To get the metrics in JSON format use: ```sh curl http[s]://:[port]/metrics.json ``` **Note:** 1. If you pass to the middleware the `metricsPath` option the path will be the one that you chose. 2. If you are using express framework and no route was found for the request (e.g: 404 status code), the request will not be collected. that's because we'll risk memory leak since the route is not a pattern but a hardcoded string. ## Custom Metrics You can expand the API metrics with more metrics that you would like to expose. All you have to do is: Require prometheus client ```js const Prometheus = require('prom-client'); ``` Create new metric from the kind that you like ```js const checkoutsTotal = new Prometheus.Counter({ name: 'checkouts_total', help: 'Total number of checkouts', labelNames: ['payment_method'] }); ``` Update it: ```js checkoutsTotal.inc({ payment_method: paymentMethod }) ``` The custom metrics will be exposed under the same endpoint as the API metrics. For more info about the Node.js Prometheus client you can read [here](https://github.com/siimon/prom-client#prometheus-client-for-nodejs--) ### Note This will work only if you use the default Prometheus registry - do not use `new Prometheus.Registry()` ## Additional Metric Labels You can define additional metric labels by using `additionalLabels` and `extractAdditionalLabelValuesFn` options. For instance: ```js const apiMetrics = require('prometheus-api-metrics'); app.use(apiMetrics({ additionalLabels: ['customer', 'cluster'], extractAdditionalLabelValuesFn: (req, res) => { const { headers } = req.headers; return { customer: headers['x-custom-header-customer'], cluster: headers['x-custom-header-cluster'] } } })) ``` ## Request.js HTTP request duration collector This feature enables you to easily process the result of Request.js timings feature. ### Usage #### Initialize You can choose to initialized this functionality as a Class or not **Class:** ```js const HttpMetricsCollector = require('prometheus-api-metrics').HttpMetricsCollector; const collector = new HttpMetricsCollector(); collector.init(); ``` **Singelton:** ```js const HttpMetricsCollector = require('prometheus-api-metrics').HttpMetricsCollector; HttpMetricsCollector.init(); ``` #### Options - durationBuckets - the histogram buckets for request duration. - countClientErrors - Boolean that indicates whether to collect client errors as Counter, this counter will have target and error code labels. - useUniqueHistogramName - Add to metrics names the project name as a prefix (from package.json) - prefix - A custom metrics names prefix, the package will add underscore between your prefix to the metric name. For Example: #### request ```js request({ url: 'http://www.google.com', time: true }, (err, response) => { Collector.collect(err || response); }); ``` #### request-promise-native ```js return requestPromise({ method: 'POST', url: 'http://www.mocky.io/v2/5bd9984b2f00006d0006d1fd', route: 'v2/:id', time: true, resolveWithFullResponse: true }).then((response) => { Collector.collect(response); }).catch((error) => { Collector.collect(error); }); ``` **Notes:** 1. In order to use this feature you must use `{ time: true }` as part of your request configuration and then pass to the collector the response or error you got. 2. In order to use the timing feature in request-promise/request-promise-native you must also use `resolveWithFullResponse: true` 3. Override - you can override the `route` and `target` attribute instead of taking them from the request object. In order to do that you should set a `metrics` object on your request with those attribute: ```js request({ method: 'POST', url: 'http://www.mocky.io/v2/5bd9984b2f00006d0006d1fd', metrics: { target: 'www.google.com', route: 'v2/:id' }, time: true }, (err, response) => {...}; }); ``` #### axios ```js const axios = require('axios'); const axiosTime = require('axios-time'); axiosTime(axios); try { const response = await axios({ baseURL: 'http://www.google.com', method: 'get', url: '/' }); Collector.collect(response); } catch (error) { Collector.collect(error); } ``` **Notes:** - In order to collect metrics from axios client the [`axios-time`](https://www.npmjs.com/package/axios-time) package is required. ## Usage in koa This package supports koa server that uses [`koa-router`](https://www.npmjs.com/package/koa-router) and [`koa-bodyparser`](https://www.npmjs.com/package/koa-bodyparser) ```js const { koaMiddleware } = require('prometheus-api-metrics') app.use(koaMiddleware()) ``` ## Test ```sh npm test ``` ## Prometheus Examples Queries ### [Apdex](https://en.wikipedia.org/wiki/Apdex) ``` (sum(rate(http_request_duration_seconds_bucket{="">, route="", le="0.05"}[10m])) by () + sum(rate(http_request_duration_seconds_bucket{="", route="", le="0.1"}[10m])) by ()) / 2 / sum(rate(http_request_duration_seconds_count{="", route=""}[10m])) by () ``` ### 95th Response Time by specific route and status code ``` histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket{="", route="", code="200"}[10m])) by (le)) ``` ### Median Response Time Overall ``` histogram_quantile(0.50, sum(rate(http_request_duration_seconds_bucket{=""}[10m])) by (le)) ``` ### Median Request Size Overall ``` histogram_quantile(0.50, sum(rate(http_request_size_bytes_bucket{=""}[10m])) by (le)) ``` ### Median Response Size Overall ``` histogram_quantile(0.50, sum(rate(http_response_size_bytes_bucket{=""}[10m])) by (le)) ``` ### Avarage Memory Usage - All services ``` avg(nodejs_external_memory_bytes / 1024 / 1024) by (

	Stars	Issues	Version	Updated	Created
appmetrics	968	72	5.1.1	4 years ago	9 years ago
metrics	574	14	0.1.21	5 years ago	13 years ago
prom-client	2,954	106	15.1.2	10 days ago	8 years ago
prometheus-api-metrics	129	43	3.2.2	2 years ago	6 years ago

appmetrics vs metrics vs prom-client vs prometheus-api-metrics

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past