---
description:
  Learn how to track and analyze GraphQL execution metrics using @graphql-mesh/plugin-prometheus.
  Expose and collect data to optimize your gateway.
---

# Prometheus

Prometheus is a platform for scraping metrics from services and utilities. You can use
`@graphql-mesh/plugin-prometheus` plugin to expose and collect metrics from all phases of your
GraphQL execution including internal query planning and outgoing HTTP requests.

This plugin tracks the complete gateway execution flow and exposes the following metrics:

- Successful 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
- Latency of outgoing HTTP request
- Latency of the delegation to the individual sources

## Getting Started

```sh npm2yarn
npm i @graphql-mesh/plugin-prometheus prom-client
```

## Example Configuration

```yaml filename=".meshrc.yaml"
# ...
plugins:
  - prometheus:
      # all optional, and by default, all set to false, please opt-in to the metrics you wish to get

      # requires `execute` to be true
      requestCount: true
      # requires `execute` to be true
      requestSummary: true
      parse: true
      validate: true
      contextBuilding: true
      execute: true
      errors: true

      # reports metrics for the delegation to the individual sources
      delegation: true

      # reports metrics for the outgoing HTTP requests
      fetchMetrics: true
      # Adds the request headers to the metrics
      fetchRequestHeaders: true
      # Adds the response headers to the metrics
      fetchResponseHeaders: true

      # reports metrics for the incoming HTTP requests (this sets a custom name for http)
      # If you pass a string instead of boolean, it will be used as the name of the metric
      http: my-http-duration-metric
      # Adds the request headers to the metrics
      httpRequestHeaders: true
      # Adds the response headers to the metrics
      httpResponseHeaders: true

      # by default all fields are reported
      deprecatedFields: true
      # the path of the endpoint to expose the metrics, default is /metrics
      endpoint: /metrics
```

> Note: 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.

## Custom Registry

You can customize the client's registry by passing a custom registry to the `registry` option.

```ts filename="myRegistry.ts"
// myRegistry.ts
import { Registry } from 'prom-client';

export default const myRegistry = new Registry();
```

```yaml filename=".meshrc.yaml"
# ...
plugins:
  - prometheus:
      # ...
      registry: ./myRegistry.ts
```

## 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.

```ts
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.

## Config API Reference

import API from '../../../generated-markdown/PrometheusConfig.generated.md'

<API />
