nexus-plugin-prometheus

A nexus-framework plugin for reporting basic GraphQL metrics through Prometheus (via prom-client)

This nexus-framework plugin collects basics GraphQL metrics and reports them to a Prometheus server. The plugin utilizes the prom-client library to communicate with Prometheus and thus requires Nexus' instance of express to be provided to the plugin.

⚠️ This plugin does NOT support Nexus projects utilizing serverless Next.JS implementations!

Installation

This module is distributed via npm which is bundled with Node.js.

npm install --save nexus-plugin-prometheus

OR

yarn add nexus-plugin-prometheus

Usage

Find a full example in the examples/basic-prometheus folder, which also includes a basic Grafana Dashboard and docker-compose file to fully illustrate the plugin in use.

Setup

Due to the middleware architecture of Nexus-framework plugins, it is vital that one use the nexus-plugin-prometheus first, so that no requests are culled by another plugin.

// app.ts

import { use, server } from 'nexus'
import { prometheus } from 'nexus-plugin-prometheus'

// Enables the Prometheus reporting plugin
use(
  prometheus({
    express: server.express, // inject Nexus express instance
  })
)

Prometheus will now be able to collect metrics from the servers /metrics url.

Running collectDefaultMetrics for collecting server metrics

Executing prom-client's collectDefaultMetrics method can be done by providing the plugin with a custom configureRegistry method.

For more information on configuring prom-client, see it's usage documentation.

// app.ts

import { use, server } from 'nexus'
import { prometheus } from 'nexus-plugin-prometheus'
import { Registry, collectDefaultMetrics } from 'prom-client'

// Define custom configuration of prom-client
function configureRegistry(): Registry[] {
  const register = new Registry()
  collectDefaultMetrics({ register })
  return [register]
}

// Enables the Prometheus reporting plugin
use(
  prometheus({
    express: server.express,
    configureRegistry, // provide custom
  })
)

Adding a prefix to my metrics

Executing prom-client's collectDefaultMetrics method with any additional configuration, such as a prefix, can be done by providing the plugin with a custom configureRegistry method.

For more information on configuring prom-client, see it's usage documentation.

// app.ts

import { use, server } from 'nexus'
import { prometheus } from 'nexus-plugin-prometheus'
import { Registry, collectDefaultMetrics } from 'prom-client'

// Define custom configuration of prom-client
function configureRegistry(): Registry[] {
  const register = new Registry()
  const prefix = 'my_application_'
  collectDefaultMetrics({ register, prefix })
  return [register]
}

// Enables the Prometheus reporting plugin
use(
  prometheus({
    express: server.express,
    configureRegistry, // provide custom
  })
)

Contributing

Please read CONTRIBUTING.md

Related

• prom-client
• Prometheus
• Grafana
• Docker

Inspiration

• dotellie/apollo-metrics
• simondujardin/graphql-middleware-prometheus
• Camji55/nexus-plugin-jwt-auth

Credits

Authored and maintained by Hays Clark.

To all contributors - Thank you!

License

Open-source under MIT License.

FAQ

• Uh oh, something went wrong!
• I wish something was different…
• Can I contribute code?
• My question isn't answered :(

Uh oh, something went wrong!

Sorry about that. It is recommended that you enable "debug" and "allowExternalErrors" in your plugin. Additionally, if you are using other Nexus plugins, you may want to do the same for them.

// app.ts

import { use, server } from 'nexus'
import { prometheus } from 'nexus-plugin-prometheus'

// Enables the Prometheus reporting plugin
use(
  prometheus({
    express: server.express,
    debug: true,
    allowExternalErrors: true,
  })
)

If you are still stuck, please submit a bug report using the GitHub issue tracker.

I wish something was different…

Keen to hear all ideas! Create an enhancement request using the GitHub issue tracker.

Can I contribute code?

Yes please! See DEVELOPING.md.

My question isn't answered :(

Ask away using the GitHub issue tracker.