@last9/openapm v0.8.0
@last9/openapm
An APM solution based on metrics and open-source tools such as Prometheus and Grafana for NodeJs-based applications.
Table of Contents
Installation
npm install --save @last9/openapm@latest
Usage
const express = require('express');
const { OpenAPM } = require('@last9/openapm');
const app = express();
const openapm = new OpenAPM();
// Instrument services
app.listen(3000);
const gracefullyShutdown = () => {
app.close(() => {
openapm
.shutdown()
.then(() => {
console.log('OpenAPM shutdown successful.');
})
.catch((err) => {
console.log('Error shutting down OpenAPM', err);
});
});
};
process.on('SIGINT', gracefullyShutdown);
process.on('SIGTERM', gracefullyShutdown);
Express
In the example below, the metrics will be served on localhost:9097/metrics
. To
change the port, you can update it through the options
(See the options documentation).
const { OpenAPM } = require('@last9/openapm');
const openapm = new OpenAPM();
openapm.instrument('express');
MySQL
This currently supports instrumentation for all Node.js ORMs, which are mysql2 compatible.
Ensure to add this line of code before you initialize db connection/pool/poolCluster
.
openapm.instrument('mysql');
NestJS
OpenAPM currently supports RED Metrics for NestJS v4 and above.
openapm.instrument('nestjs');
Next.js
OpenAPM supports RED metrics for both pages and app router in a Next.js application.
openapm.instrument('nextjs');
Note: You can only use the library if Next.js runs in a Node.js environment. Since OpenAPM relies on prom-client for capturing metrics data, a serverless environment might not be able persist them.
Options
Usage
const openapm = new OpenAPM({
// Options go here
});
path
: The path at which the metrics will be served. For eg./metrics
metricsServerPort
: (Optional) The port at which the metricsServer will run.environment
: (Optional) The application environment. Defaults toproduction
.defaultLabels
: (Optional) Any default labels to be included.requestsCounterConfig
: (Optional) Requests counter configuration, same as Counter inprom-client
. Defaults to{ name: 'http_requests_total', help: 'Total number of requests', labelNames: ['path', 'method', 'status'], }
requestDurationHistogramConfig
: (Optional) Requests Duration histogram configuration, the same as Histogram inprom-client
. Defaults to{ name: 'http_requests_duration_milliseconds', help: 'Duration of HTTP requests in milliseconds', labelNames: ['path', 'method', 'status'], buckets: promClient.exponentialBuckets(0.25, 1.5, 31), }
extractLabels
: (Optional) Extract labels from URL params (WIP: Headers, Subdomain)// To extract from the URL params { ... extractLabels: { tenant: { // Here 'tenant' is the label name from : 'params', key: 'org' // Which key to extract from the params mask: ':org' // Replacement string } } }
excludeDefaultLabels
: (Optional) Provide labels to exclude from the default labels
{
...
excludeDefaultLabels: ['environment', 'version']
}
levitateConfig
: (Optional) Configuration for Levitate TSDB. Adding this configuration will enable the Change Events.enableMetricsServer
: (Optional) Defaults totrue
. When set tofalse
the OpenAPM won't start a metrics server. To get the metrics users can rely on the.getMetrics()
function.
{
...
levitateConfig: {
host: 'https://app.last9.io',
orgSlug: 'last9', /** The slug can be obtained from the Last9 dashboard.*/
dataSourceName: 'data-source', /** The data source can be obtained from the data source pages in the Last9 dashboard*/
refreshTokens: {
write: '0d2a1a9a45XXXXXXXXXXXXXX3f1342790d2a1a9a45XXXXXXXXXXXXXX3f1342790d2a1a9a45XXXXXXXXXXXXXX3f134279' /** You can get this from the API access page on Last9 dashboard*/
}
}
}
API Reference
instrument
: Used to instrument supported technologies. Refer the usage section.getMetrics
: Returns a Promise of string which contains metrics in Prometheus exposition format. You can use this function to expose a metrics endpoint ifenableMetricsServer
is set to false. For example,
const openapm = new OpenAPM({
enableMetricsServer: false
});
openapm.instrument('express');
const app = express();
app.get('/metrics', async (_, res) => {
const metrics = await openapm.getMetrics();
res.setHeader('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
res.end(metrics);
});
shutdown
: Returns a promise which is resolved after the cleanup in OpenAPM. The cleanup includes closing the metrics server if it has started and cleared the prom-client register.
const gracefullyShutdown = () => {
server.close(() => {
openapm
.shutdown()
.then(() => {
console.log('OpenAPM shutdown successful.');
})
.catch((err) => {
console.log('Error shutting down OpenAPM', err);
});
});
};
process.on('SIGINT', gracefullyShutdown);
process.on('SIGTERM', gracefullyShutdown);
Setup locally
Make sure you are in the express directory.
- Install packages
npm install
Build package
- This will build the package and store the JS and type declaration files in
the
dist
folder.
- This will build the package and store the JS and type declaration files in
the
npm run build
Grafana Dashboard View
- Import this dashboard into your Grafana
- Select your data source
- Save the dashboard
About Last9
Last9 builds reliability tools for SRE and DevOps.
11 days ago
15 days ago
15 days ago
15 days ago
15 days ago
16 days ago
19 days ago
19 days ago
19 days ago
19 days ago
24 days ago
24 days ago
24 days ago
24 days ago
24 days ago
24 days ago
27 days ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
1 month ago
2 months ago
4 months ago
4 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
5 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
6 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
8 months ago
8 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
9 months ago
10 months ago
10 months ago
10 months ago