The Guild LogoThe Guild Monogram
Envelop Logo

Envelop

Get Started

Plugin Hub > usePrometheus

yarn add @envelop/prometheus

@envelop/prometheus#

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

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

  • Sucessfull requests (requestCount)
  • Request summary (requestSummary)
  • errors (categorized by phase)
  • resolvers tracing and runtime
  • deprecated fields usage
  • count of graphql operations
  • parse execution time
  • validate execution time
  • contextBuilding execution time
  • execute execution time

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

Getting Started#

yarn add prom-client @envelop/prometheus

Usage Example#

import { envelop } from '@envelop/core'; import { usePrometheus } from '@envelop/prometheus'; const getEnveloped = envelop({ plugins: [ // ... other plugins ... usePrometheus({ // all optional, and by default, all set to false, please opt-in to the metrics you wish to get requestCount: true, // requries `execute` to be true as well requestSummary: true, // requries `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 }), ], });

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

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 { Registry } from 'prom-client'; const myRegistry = new Registry(); const getEnveloped = envelop({ plugins: [ // ... 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.

Custom prom-client instances#

Each tracing field supports custom prom-client objects, and custom labels a metadata, you can create a custom extraction function for every Histogram / Summary / Counter:

import { Histogram } from 'prom-client'; import { envelop } from '@envelop/core'; import { createHistogram, usePrometheus } from '@envelop/prometheus'; const getEnveloped = envelop({ plugins: [ // ... other plugins ... usePrometheus({ // all optional, and by default, all set to false, please opt-in to the metrics you wish to get parse: createHistogram({ histogram: new Histogram({ name: 'my_custom_name', help: 'HELP ME', labelNames: ['opText'] as const, registers: [registry], // make sure to add your custom registry, if you are not using the default one }), fillLabelsFn: params => { // if you wish to fill your `lables` 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), }; }, }), }), ], });

Plugin Details

Edit on GitHub