Awesome
<div align="center"> <img src="https://i.imgur.com/ny3ka9X.png" /> </div>adonisjs-prometheus
📊 Prometheus package for AdonisJS
Installation
node ace add @julr/adonisjs-prometheus
Usage
After installing the package, a configuration file is added to config/prometheus.ts
in your application.
export default defineConfig({
/**
* Endpoint where metrics will be exposed
*/
endpoint: '/metrics',
/**
* A prefix that will be added to all metrics
* names
*/
metricsPrefix: env.get('APP_NAME'),
/**
* List of IPs that are allowed to access the
* metrics endpoint. If empty, then everyone
* can access the endpoint
*/
ipsWhitelist: [],
/**
* List of collectors that will be registered
* and expose new metrics.
*
* Feel free to remove collectors that you
* don't want to use
*/
collectors: [
httpCollector(),
mailCollector(),
lucidCollector(),
cacheCollector(),
systemCollector(),
],
})
The available options are:
endpoint
: The URL of the endpoint where metrics will be exposed. Defaults to/metrics
.metricsPrefix
: A prefix that will be added to all metric names. Defaults to the app name.ipsWhitelist
: A list of IP addresses allowed to access the metrics endpoint. If empty, everyone can access it. Defaults to an empty array.collectors
: The list of collectors that will be registered and expose new metrics. You can remove collectors you don't want to use.
Collectors
Each collector accepts options to customize the metrics it exposes. Be sure to explore these options using your editor's auto-completion to learn more.
HTTP Collector
Adds metrics to monitor HTTP requests:
Exposed Metrics
http_requests_total
: Counter for the total number of HTTP requests.http_request_duration_seconds
: Histogram of HTTP request durations.
Options
shouldGroupStatusCode
: Groups HTTP status codes into 1xx, 2xx, 3xx, 4xx, and 5xx. Defaults tofalse
.excludedRoutes
: A list of routes to exclude from metrics. Defaults to an empty array. You can pass a list ofstring
or a function(ctx: HttpContext) => boolean
.requestDuration.buckets
: The buckets for the histogram of HTTP request durations.
System Collector
Adds metrics to monitor the host system's performance. See Default Metrics for more information. The collector accepts the same options as the prom-client
collectDefaultMetrics
function.
Lucid Collector
Adds metrics to monitor database queries made through @adonisjs/lucid
.
[!IMPORTANT] To use the Lucid collector, you must set
debug: true
in yourconfig/database.ts
file.
Exposed Metrics
lucid_query_duration_seconds
: Histogram of Lucid query durations. Labels includeconnection
,model
, andmethod
.
Options
queryDuration.buckets
: The buckets for the histogram of Lucid query durations.
Cache Collector
Adds metrics to monitor @adonisjs/cache
operations.
Exposed Metrics
cache_hits_total
: Counter for the total number of cache hits.cache_misses_total
: Counter for the total number of cache misses.cache_writes_total
: Counter for the total number of cache writes.
Mail Collector
Adds metrics to monitor emails sent through @adonisjs/mail
.
Exposed Metrics
mails_sent_total
: Counter for the total number of emails sent.
Custom metrics
To add your own metrics, you have two options:
Use prom-client
You can directly use prom-client
with the same registry :
import { Counter } from 'prom-client'
export const orderMetrics = new Counter({
name: 'sent_orders',
help: 'Total Orders Sent',
})
export default class OrderController {
public async store({ request }: HttpContext) {
// ...
OrderMetric.inc()
// ...
}
}
Create a custom collector
You can also create a custom collector to expose your metrics:
import { Collector } from '@julr/adonisjs-prometheus/collectors/collector'
export function appOrdersCollector() {
return configProvider.create(async (app) => {
const emitter = await app.container.make('emitter')
const config = app.config.get<ResolvedPromConfig>('prometheus')
return new MailCollector(emitter, config)
})
}
export class AppOrdersCollector extends Collector {
constructor(
private emitter: EmitterService,
options: CommonCollectorOptions,
) {
super(options)
}
async register() {
const orderMetrics = this.createGauge({
name: 'sent_orders',
help: 'Total Orders Sent',
})
/**
* Let's imagine that your emitter emits a `new:order` event.
* This is one way to collect metrics, but you can do it the way you want :
* - Using a listener
* - Using a DB Query and the `collect()` method of the gauge
* - etc.
*/
this.emitter.on('new:order', () => orderMetrics.inc())
}
}
Then, add your collector to the config/prometheus.ts
configuration file:
export default defineConfig({
// ...
collectors: [
// ...
appOrdersCollector(),
],
})
Sponsors
If you like this project, please consider supporting it by sponsoring it. It will help a lot to maintain and improve it. Thanks a lot !