v5 (latest)
Features
Monitoring

Monitoring

Once in production, it’s important to monitor your GraphQL server.

A common way to monitor your server is by using Prometheus, a popular, free and open-source monitoring system.

Getting Started

To get started, you need to install the @graphql-yoga/plugin-prometheus package.

This plugin tracks the complete execution flow, and reports metrics using Prometheus tracing (based on prom-client).

npm i prom-client @graphql-yoga/plugin-prometheus

You can then add the plugin to your GraphQL server:

import { execute, parse, specifiedRules, subscribe, validate } from 'graphql'
import { envelop, useEngine } from '@envelop/core'
import { usePrometheus } from '@envelop/prometheus'
 
const getEnveloped = envelop({
  plugins: [
    useEngine({ parse, validate, specifiedRules, execute, subscribe }),
    // ... other plugins ...
    usePrometheus({
      endpoint: '/metrics', // optional, default is `/metrics`, you can disable it by setting it to `false` if registry is configured in "push" mode
      // all optional, and by default, all set to false, please opt-in to the metrics you wish to get
      requestCount: true, // requires `execute` to be true as well
      requestSummary: true, // requires `execute` to be true as well
      parse: true,
      validate: true,
      contextBuilding: true,
      execute: true,
      errors: true,
      resolvers: true, // requires "execute" to be `true` as well
      resolversWhitelist: ['Mutation.*', 'Query.user'], // reports metrics als for these resolvers, leave `undefined` to report all fields
      deprecatedFields: true,
      registry: myRegistry // If you are using a custom prom-client registry, please set it here
    })
  ]
})
⚠️

Tracing resolvers using resolvers: true might have a performance impact on your GraphQL runtime. Please consider to test it locally first and then decide if it’s needed.

Now, you can access the metrics by visiting the /metrics endpoint of your server.

You can then configure Prometheus to scrape the metrics from your server by using this URL.

Configuration

Available metrics

You can opt-in to collect tracing from the following phases:

  • HTTP request process time (http)
  • Graphql successful requests (requestCount)
  • Graphql request summary (requestSummary)
  • errors (categorized by phase)
  • resolvers tracing and runtime
  • deprecated fields usage (deprecatedFields)
  • parse execution time
  • validate execution time
  • contextBuilding execution time
  • execute execution time
  • subscribe execution time
  • count of schema changes (schemaChangeCount)

You can also customize each phase reporter, and add custom metadata and labels to the metrics.

Custom registry

You can customize the prom-client Registry object if you are using a custom one, by passing it along with the configuration object:

import { execute, parse, specifiedRules, subscribe, validate } from 'graphql'
import { Registry } from 'prom-client'
import { envelop, useEngine } from '@envelop/core'
 
const myRegistry = new Registry()
 
const getEnveloped = envelop({
  plugins: [
    useEngine({ parse, validate, specifiedRules, execute, subscribe }),
    // ... other plugins ...
    usePrometheus({
      // ... config ...
      registry: myRegistry
    })
  ]
})

Note: if you are using custom prom-client instances, you need to make sure to pass your registry there as well.

Introspection

If you wish to disable introspection logging, you can use skipIntrospection: true in your config object.

Customize metrics options and labels

Each metric can be configured and custom labels can be added to provide more metadata. You can create a custom extraction function for every Histogram / Summary / Counter:

import { execute, parse, specifiedRules, subscribe, validate } from 'graphql'
import { Histogram, register as registry } from 'prom-client'
import { envelop, useEngine } from '@envelop/core'
import { createHistogram, usePrometheus } from '@envelop/prometheus'
 
const getEnveloped = envelop({
  plugins: [
    useEngine({ parse, validate, specifiedRules, execute, subscribe }),
    // ... other plugins ...
    usePrometheus({
      // all optional, and by default, all set to false, please opt-in to the metrics you wish to get
      parse: createHistogram({
        registry: registry // make sure to add your custom registry, if you are not using the default one
        histogram: new Histogram({
          name: 'my_custom_name',
          help: 'HELP ME',
          labelNames: ['opText'] as const,
        }),
        fillLabelsFn: params => {
          // if you wish to fill your `labels` with metadata, you can use the params in order to get access to things like DocumentNode, operationName, operationType, `error` (for error metrics) and `info` (for resolvers metrics)
          return {
            opText: print(params.document)
          }
        }
      })
    })
  ]
})

Caveats

Due to Prometheus client API limitations, if this plugin is initialized multiple times, only the metrics configuration of the first initialization will be applied.

If necessary, use a different registry instance for each plugin instance, or clear the registry before plugin initialization.

function usePrometheusWithRegistry() {
  // create a new registry instance for each plugin instance
  const registry = new Registry()
 
  // or just clear the registry if you use only on plugin instance at a time
  registry.clear()
 
  return usePrometheus({
    registry,
    ...
  })
}

Keep in mind that this implies potential data loss in pull mode if some data is produced between last pull and the re-initialization of the plugin.

Request CustomizationPrepare for Production