appmetrics-prometheus
appmetrics-prometheus provides a /metrics endpoint which is necessary for Prometheus monitoring.
The data available on the /metrics endpoint is as follows:
- CPU
- os_cpu_used_ratio (Ratio of systems CPU currently in use, type: gauge)
- process_cpu_used_ratio (Ratio of process CPU currently in use, type: gauge)
- Memory
- os_resident_memory_bytes (OS memory size in bytes, type: gauge)
- process_resident_memory_bytes (Resident memory size in bytes, type: gauge)
- process_virtual_memory_bytes (Virtual memory size in bytes, type: gauge)
- HTTP
- http_requests_total (Total number of HTTP requests made, type: counter)
- http_request_duration_microseconds (The HTTP request latencies in microseconds, type: summary)
appmetrics-prometheus uses Node Application Metrics to monitor the application.
Configuring Prometheus
Prometheus Documentation
Local Installation
Download Prometheus from: Prometheus Downloads.
Follow the instructions on the Prometheus getting started page.
Or follow the simple example below.
Install Prometheus using:
tar xvfz prometheus-*.tar.gz
cd prometheus-*
Next you need to modify the configuration file that Prometheus uses.
In the prometheus folder there is a file named prometheus.yml
.
In this file you can alter which IP addresses and port numbers are scraped by Prometheus and also how often the scraping occurs.
global:
scrape_interval: 15s # By default, scrape targets every 15 seconds.
# Attach these labels to any time series or alerts when communicating with
# external systems (federation, remote storage, Alertmanager).
external_labels:
monitor: 'codelab-monitor'
# A scrape configuration:
scrape_configs:
# The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
- job_name: 'YOUR JOB NAME'
# Override the global default and scrape targets from this job every 5 seconds.
scrape_interval: 5s
static_configs:
- targets: ['IPADDRESS:PORT', 'IPADDRESS:PORT']
Set the targets field to your IP address and port number. You can monitor many applications by adding a comma between each IP address and port number.
Start Prometheus by using the command:
./prometheus -config.file=prometheus.yml
Prometheus can be found at localhost:9090
.
Installation
npm install appmetrics-prometheus
Usage
Place the following code at the top of your applications server file.
require('appmetrics-prometheus').attach()
or to use preloading:
$ node --require appmetrics-prometheus/attach app.js
or to explicitly attach the express endpoint:
app.use('/metrics', require('appmetrics-prometheus').endpoint());
prometheus = require('appmetrics-prometheus').attach()
This will launch the prometheus endpoint and start monitoring your application.
The prometheus metrics page is located at /metrics.
Simple example using the express framework.
var express = require('express');
var prometheus = require('appmetrics-prometheus').attach();
var cfenv = require('cfenv');
var app = express();
app.use(express.static(__dirname + '/public'));
var appEnv = cfenv.getAppEnv();
var server = app.listen(appEnv.port, '0.0.0.0', function() {
console.log("server starting on " + appEnv.url);
});
prometheus.attach(options)
- options.appmetrics {Object} An instance of
require('appmetrics')
can be
injected if the application wants to use appmetrics, since it is a singleton
module and only one can be present in an application. Optional, defaults to
the appmetrics dependency of this module.
Auto-attach to all http
servers created after this call, calling prometheus.monitor(options)
for every server.
Simple example using attach.
require('appmetrics-prometheus').attach();
var http = require('http');
const port = 3000;
const requestHandler = (request, response) => {
response.end('Hello')
}
const server = http.createServer(requestHandler);
server.listen(port, (err) => {
if (err) {
return console.log('An error occurred', err)
}
console.log(`Server is listening on ${port}`)
});
prometheus.endpoint(options)
Returns an endpoint that can be used as express middleware. Options are the same
as for prometheus.attach(options)
.
var express = require('express');
var cfenv = require('cfenv');
var app = express();
app.use('/metrics', require('appmetrics-prometheus').endpoint());
app.use(express.static(__dirname + '/public'));
var appEnv = cfenv.getAppEnv();
app.listen(appEnv.port, '0.0.0.0', function() {
console.log('server starting on ' + appEnv.url);
});
Performance overhead
Our testing has shown that the performance overhead in terms of processing is minimal, adding less than 0.5 % to the CPU usage of your application.
We gathered this information by monitoring the sample application Acme Air. We used MongoDB as our datastore and used JMeter to drive load though the program. We have performed this testing with Node.js version 6.10.3.
Contributing
We welcome contributions. Please see CONTRIBUTING.md for details about the contributor licence agreement and other information. If you want to do anything more involved than a bug fix or a minor enhancement then we would recommend discussing it in an issue first before doing the work to make sure that it's likely to be accepted. We're also keen to improve test coverage and may not accept new code unless there are accompanying tests.
Module Long Term Support Policy
This module adopts the Module Long Term Support (LTS) policy, with the following End Of Life (EOL) dates:
Module Version | Release Date | Minimum EOL | EOL With | Status |
---|
V2.x.x | Jun 2018 | Dec 2019 | | Current |
Version
3.1.0
License
Apache-2.0