{"id":15481847,"url":"https://github.com/julien-r44/adonisjs-prometheus","last_synced_at":"2025-04-15T01:29:22.276Z","repository":{"id":53699585,"uuid":"439720732","full_name":"Julien-R44/adonisjs-prometheus","owner":"Julien-R44","description":"📊 Prometheus Provider for AdonisJS with some builtins metrics for monitoring your application.","archived":false,"fork":false,"pushed_at":"2024-05-27T23:09:28.000Z","size":515,"stargazers_count":43,"open_issues_count":2,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-29T23:30:22.421Z","etag":null,"topics":["adonisjs","adonisjs5","prometheus","prometheus-exporter"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Julien-R44.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["julien-r44"],"polar":"Julien-R44"}},"created_at":"2021-12-18T21:44:04.000Z","updated_at":"2024-09-26T15:13:51.000Z","dependencies_parsed_at":"2024-01-15T09:07:56.384Z","dependency_job_id":"1446c71b-d0e5-4f5d-b0fd-ac255782c2a7","html_url":"https://github.com/Julien-R44/adonisjs-prometheus","commit_stats":{"total_commits":50,"total_committers":1,"mean_commits":50.0,"dds":0.0,"last_synced_commit":"0e77832d5c90e6fde0261e88d6b1bec00c2ae53d"},"previous_names":["julien-r44/adonis5-prometheus"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Julien-R44%2Fadonisjs-prometheus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Julien-R44%2Fadonisjs-prometheus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Julien-R44%2Fadonisjs-prometheus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Julien-R44%2Fadonisjs-prometheus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Julien-R44","download_url":"https://codeload.github.com/Julien-R44/adonisjs-prometheus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248988622,"owners_count":21194450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adonisjs","adonisjs5","prometheus","prometheus-exporter"],"created_at":"2024-10-02T05:06:36.181Z","updated_at":"2025-04-15T01:29:22.266Z","avatar_url":"https://github.com/Julien-R44.png","language":"TypeScript","funding_links":["https://github.com/sponsors/julien-r44","https://polar.sh/Julien-R44","https://github.com/sponsors/Julien-R44/"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://i.imgur.com/ny3ka9X.png\"  /\u003e  \n\u003c/div\u003e\n\n# adonisjs-prometheus \n\n📊 Prometheus package for AdonisJS\n\n## Installation\n\n```sh\nnode ace add @julr/adonisjs-prometheus\n```\n\n## Usage\n\nAfter installing the package, a configuration file is added to `config/prometheus.ts` in your application.\n\n```ts\nexport default defineConfig({\n  /**\n   * Endpoint where metrics will be exposed\n   */\n  endpoint: '/metrics',\n\n  /**\n   * A prefix that will be added to all metrics\n   * names\n   */\n  metricsPrefix: env.get('APP_NAME'),\n\n  /**\n   * List of IPs that are allowed to access the\n   * metrics endpoint. If empty, then everyone\n   * can access the endpoint\n   */\n  ipsWhitelist: [],\n\n  /**\n   * List of collectors that will be registered\n   * and expose new metrics.\n   *\n   * Feel free to remove collectors that you\n   * don't want to use\n   */\n  collectors: [\n    httpCollector(),\n    mailCollector(),\n    lucidCollector(),\n    cacheCollector(),\n    systemCollector(),\n  ],\n})\n```\n\nThe available options are:\n\n- `endpoint`: The URL of the endpoint where metrics will be exposed. Defaults to `/metrics`.\n- `metricsPrefix`: A prefix that will be added to all metric names. Defaults to the app name.\n- `ipsWhitelist`: A list of IP addresses allowed to access the metrics endpoint. If empty, everyone can access it. Defaults to an empty array.\n- `collectors`: The list of collectors that will be registered and expose new metrics. You can remove collectors you don't want to use.\n\n## Collectors\n\nEach collector accepts options to customize the metrics it exposes. Be sure to explore these options using your editor's auto-completion to learn more.\n\n### HTTP Collector\n\nAdds metrics to monitor HTTP requests:\n\n#### Exposed Metrics\n\n- `http_requests_total`: Counter for the total number of HTTP requests.\n- `http_request_duration_seconds`: Histogram of HTTP request durations.\n\n#### Options\n\n- `shouldGroupStatusCode`: Groups HTTP status codes into 1xx, 2xx, 3xx, 4xx, and 5xx. Defaults to `false`.\n- `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) =\u003e boolean`.\n- `requestDuration.buckets`: The buckets for the histogram of HTTP request durations.\n\n### System Collector\n\nAdds 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.\n\n### Lucid Collector\n\nAdds metrics to monitor database queries made through `@adonisjs/lucid`.\n\n\u003e [!IMPORTANT]\n\u003e To use the Lucid collector, you must set `debug: true` in your `config/database.ts` file.\n\n#### Exposed Metrics\n\n- `lucid_query_duration_seconds`: Histogram of Lucid query durations. Labels include `connection`, `model`, and `method`.\n\n#### Options\n\n- `queryDuration.buckets`: The buckets for the histogram of Lucid query durations.\n\n### Cache Collector\n\nAdds metrics to monitor `@adonisjs/cache` operations.\n\n#### Exposed Metrics\n\n- `cache_hits_total`: Counter for the total number of cache hits.\n- `cache_misses_total`: Counter for the total number of cache misses.\n- `cache_writes_total`: Counter for the total number of cache writes.\n\n### Mail Collector\n\nAdds metrics to monitor emails sent through `@adonisjs/mail`.\n\n#### Exposed Metrics\n\n- `mails_sent_total`: Counter for the total number of emails sent.\n\n## Custom metrics\n\nTo add your own metrics, you have two options:\n\n### Use prom-client\n\nYou can directly use `prom-client` with the same registry :\n\n```ts\nimport { Counter } from 'prom-client'\n\nexport const orderMetrics = new Counter({\n  name: 'sent_orders',\n  help: 'Total Orders Sent',\n})\n\nexport default class OrderController {\n  public async store({ request }: HttpContext) {\n    // ...\n    OrderMetric.inc()\n    // ...\n  }\n}\n```\n\n### Create a custom collector\n\nYou can also create a custom collector to expose your metrics:\n\n```ts\nimport { Collector } from '@julr/adonisjs-prometheus/collectors/collector'\n\nexport function appOrdersCollector() {\n  return configProvider.create(async (app) =\u003e {\n    const emitter = await app.container.make('emitter')\n    const config = app.config.get\u003cResolvedPromConfig\u003e('prometheus')\n\n    return new MailCollector(emitter, config)\n  })\n}\n\nexport class AppOrdersCollector extends Collector {\n  constructor(\n    private emitter: EmitterService,\n    options: CommonCollectorOptions,\n  ) {\n    super(options)\n  }\n\n  async register() {\n    const orderMetrics = this.createGauge({\n      name: 'sent_orders',\n      help: 'Total Orders Sent',\n    })\n\n    /**\n     * Let's imagine that your emitter emits a `new:order` event.\n     * This is one way to collect metrics, but you can do it the way you want :\n     * - Using a listener\n     * - Using a DB Query and the `collect()` method of the gauge\n     * - etc.\n     */\n    this.emitter.on('new:order', () =\u003e orderMetrics.inc())\n  }\n}\n```\n\nThen, add your collector to the `config/prometheus.ts` configuration file:\n\n```ts\nexport default defineConfig({\n  // ...\n  collectors: [\n    // ...\n    appOrdersCollector(),\n  ],\n})\n```\n\n## Sponsors\n\nIf 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 !\n\n![](https://github.com/julien-r44/static/blob/main/sponsorkit/sponsors.png?raw=true)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulien-r44%2Fadonisjs-prometheus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjulien-r44%2Fadonisjs-prometheus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulien-r44%2Fadonisjs-prometheus/lists"}