https://github.com/Julien-R44/adonisjs-prometheus
📊 Prometheus Provider for AdonisJS with some builtins metrics for monitoring your application.
https://github.com/Julien-R44/adonisjs-prometheus
adonisjs adonisjs5 prometheus prometheus-exporter
Last synced: 2 months ago
JSON representation
📊 Prometheus Provider for AdonisJS with some builtins metrics for monitoring your application.
- Host: GitHub
- URL: https://github.com/Julien-R44/adonisjs-prometheus
- Owner: Julien-R44
- License: mit
- Created: 2021-12-18T21:44:04.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-02-06T18:10:56.000Z (5 months ago)
- Last Synced: 2025-05-07T21:02:19.800Z (2 months ago)
- Topics: adonisjs, adonisjs5, prometheus, prometheus-exporter
- Language: TypeScript
- Homepage:
- Size: 284 KB
- Stars: 77
- Watchers: 3
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-adonisjs - Adonis Prometheus - Prometheus Provider for Adonis 5 with some builtins metrics for monitoring your application. (Packages)
README
# adonisjs-prometheus
📊 Prometheus package for AdonisJS
## Installation
```sh
node ace add @julr/adonisjs-prometheus
```
## Usage
After installing the package, a configuration file is added to `config/prometheus.ts` in your application.
```ts
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 to `false`.
- `excludedRoutes`: A list of routes to exclude from metrics. Defaults to an empty array. You can pass a list of `string` 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](https://github.com/siimon/prom-client#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 your `config/database.ts` file.
#### Exposed Metrics
- `lucid_query_duration_seconds`: Histogram of Lucid query durations. Labels include `connection`, `model`, and `method`.
#### 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 :
```ts
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:
```ts
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('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:
```ts
export default defineConfig({
// ...
collectors: [
// ...
appOrdersCollector(),
],
})
```
## Sponsors
If you like this project, [please consider supporting it by sponsoring it](https://github.com/sponsors/Julien-R44/). It will help a lot to maintain and improve it. Thanks a lot !
