Monitoring and Tracing

By default, the plugin will a root span for the HTTP layer as a span (METHOD /path) with the following attributes for the HTTP request:

• http.method: The HTTP method
• http.url: The HTTP URL
• http.route: The HTTP status code
• http.scheme: The HTTP scheme
• http.host: The HTTP host
• net.host.name: The hostname
• http.user_agent: The HTTP user agent (based on the User-Agent header)
• http.client_ip: The HTTP connecting IP (based on the X-Forwarded-For header)

And the following attributes for the HTTP response:

• http.status_code: The HTTP status code

An error in the this phase will be reported as an error span with the HTTP status text and as an OpenTelemetry Exception.

You may disable this by setting spans.http to false:

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  openTelemetry: {
    exporters: [
      /* ... */
    ],
    spans: {
      /* ... */
      http: false
    }
  }
})

Or, you may filter the spans by setting the spans configuration to a function:

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  openTelemetry: {
    exporters: [
      /* ... */
    ],
    spans: {
      /* ... */
      http: payload => {
        // Filter the spans based on the payload
        return true
      }
    }
  }
})

The payload object is the same as the one passed to the onRequest hook.

By default, the plugin will report the validation phase as a span (graphql.validate) with the following attributes:

• graphql.document: The GraphQL query string
• graphql.operation.name: The operation name

An error in the parse phase will be reported as an error span, including the error message and as an OpenTelemetry Exception.

You may disable this by setting spans.graphqlParse to false:

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  openTelemetry: {
    exporters: [
      /* ... */
    ],
    spans: {
      /* ... */
      graphqlParse: false
    }
  }
})

Or, you may filter the spans by setting the spans configuration to a function:

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  openTelemetry: {
    exporters: [
      /* ... */
    ],
    spans: {
      /* ... */
      graphqlParse: payload => {
        // Filter the spans based on the payload
        return true
      }
    }
  }
})

The payload object is the same as the one passed to the onParse hook.

By default, the plugin will report the validation phase as a span (graphql.validate) with the following attributes:

• graphql.document: The GraphQL query string
• graphql.operation.name: The operation name

An error in the validate phase will be reported as an error span, including the error message and as an OpenTelemetry Exception.

You may disable this by setting spans.graphqlValidate to false:

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  openTelemetry: {
    exporters: [
      /* ... */
    ],
    spans: {
      /* ... */
      graphqlValidate: false
    }
  }
})

Or, you may filter the spans by setting the spans configuration to a function:

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  openTelemetry: {
    exporters: [
      /* ... */
    ],
    spans: {
      /* ... */
      graphqlValidate: payload => {
        // Filter the spans based on the payload
        return true
      }
    }
  }
})

The payload object is the same as the one passed to the onValidate hook.

By default, the plugin will report the execution phase as a span (graphql.execute) with the following attributes:

• graphql.document: The GraphQL query string
• graphql.operation.name: The operation name
• graphql.operation.type: The operation type (query/mutation/subscription)

An error in the execute phase will be reported as an error span, including the error message and as an OpenTelemetry Exception.

You may disable this by setting spans.graphqlExecute to false:

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  openTelemetry: {
    exporters: [
      /* ... */
    ],
    spans: {
      /* ... */
      graphqlExecute: false
    }
  }
})

Or, you may filter the spans by setting the spans configuration to a function:

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  openTelemetry: {
    exporters: [
      /* ... */
    ],
    spans: {
      /* ... */
      graphqlExecute: payload => {
        // Filter the spans based on the payload
        return true
      }
    }
  }
})

The payload object is the same as the one passed to the onExecute hook.

By default, the plugin will report the subgraph execution phase as a span (subgraph.execute) with the following attributes:

• graphql.document: The GraphQL query string executed to the upstream
• graphql.operation.name: The operation name
• graphql.operation.type: The operation type (query/mutation/subscription)
• gateway.upstream.subgraph.name: The name of the upstream subgraph

In addition, the span will include the following attributes for the HTTP requests;

• http.method: The HTTP method
• http.url: The HTTP URL
• http.route: The HTTP status code
• http.scheme: The HTTP scheme
• net.host.name: The hostname
• http.host: The HTTP host

And the following attributes for the HTTP response:

• http.status_code: The HTTP status code

You may disable this by setting spans.subgraphExecute to false:

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  openTelemetry: {
    exporters: [
      /* ... */
    ],
    spans: {
      /* ... */
      subgraphExecute: false
    }
  }
})

Or, you may filter the spans by setting the spans.subgraphExecute configuration to a function:

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  openTelemetry: {
    exporters: [
      /* ... */
    ],
    spans: {
      /* ... */
      subgraphExecute: payload => {
        // Filter the spans based on the payload
        return true
      }
    }
  }
})

The payload object is the same as the one passed to the onSubgraphHook hook.

By default, the plugin will report the upstream fetch phase as a span (http.fetch) with the information about outgoing HTTP calls.

The following attributes are included in the span:

• http.method: The HTTP method
• http.url: The HTTP URL
• http.route: The HTTP status code
• http.scheme: The HTTP scheme
• net.host.name: The hostname
• http.host: The HTTP host

And the following attributes for the HTTP response:

• http.status_code: The HTTP status code

You may disable this by setting spans.upstreamFetch to false:

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  openTelemetry: {
    exporters: [
      /* ... */
    ],
    spans: {
      /* ... */
      upstreamFetch: false
    }
  }
})

Or, you may filter the spans by setting the spans.upstreamFetch configuration to a function:

import { defineConfig } from '@graphql-hive/gateway'
 
export const gatewayConfig = defineConfig({
  openTelemetry: {
    exporters: [
      /* ... */
    ],
    spans: {
      /* ... */
      upstreamFetch: payload => {
        // Filter the spans based on the payload
        return true
      }
    }
  }
})

The payload object is the same as the one passed to the onFetch hook.

This metric tracks the duration of incoming (downstream) HTTP requests. It reports the time spent to process each incoming request as a histogram.

It is useful to track the responsiveness of your gateway. A spike in this metric could indicate a performance issue and that further investigation is needed.

Please note that this metric is not specific to GraphQL, it tracks all incoming HTTP requests.

You can use labels to have a better understanding of the requests and group them together. A common filter is to include only statusCode with 200 value and method with POST (the default method for GraphQL requests, but it can also be GET depending on your client setup) value to get execution time of successful GraphQL requests only.

This metric includes some useful labels to help you identify requests and group them together.

This metric tracks the duration of outgoing HTTP requests. It reports the time spent on each request made using the fetch function provided by the gateway. It is reported as a histogram.

This metric can provide insights into the network usage of your gateway. It does not only include requests made to resolve GraphQL operation responses, but also include any other outgoing HTTP requests made by the gateway or one of its plugins. It will for example include requests made to fetch the supergraph schema from the configured Schema Registry.

These metrics include some useful labels to help you identify requests and group them together.

Since they can be heavy, requestHeaders and responseHeaders are disabled by default. You can either set those options to true in the label configuration object to include all headers in the label, but you can also provide a list of header names to include.

This metric tracks the duration of subgraph execution. It reports the time spent on each subgraph queries made to resolve incoming operations as a histogram.

This metric can provide insights into how the time is spent to resolve queries. It can help you identify bottlenecks in your subgraphs.

This metric tracks the number of errors that occurred during the subgraph execution. It counts all errors found in the response returned by the subgraph execution. It is exposed as a counter.

This metric can help you identify subgraphs that are failing to execute operations. It can help identify issues with the subgraph itself or the communication between the gateway and the subgraph.

This metric tracks the duration of the parse phase of the GraphQL execution. It reports the time spent parsing the incoming GraphQL operation. It is reported as a histogram.

Since you don’t have control over the parsing phase, this metric is mostly useful to track potential attacks. A spike in this metric could indicate someone is trying to send malicious operations to your gateway.

This metric tracks the duration of the validate phase of the GraphQL execution. It reports the time spent validating the incoming GraphQL operation. It is reported as a histogram.

This metric tracks the duration of the context phase of the GraphQL execution. It reports the time spent building the context object that will be passed to the executors. It is reported as a histogram.

This metric tracks the duration of the execute phase of the GraphQL execution. It reports the time spent actually resolving the response of the incoming operation. This includes the gathering of all the data from all sources required to construct the final response. It is reported as a histogram.

It is the metric that will give you the most insights into the performance of your gateway, since this is where most of the work is done.

This metric tracks the duration of the subscribe phase of the GraphQL execution. It reports the time spent initiating a subscription (which doesn’t include actually sending the first response). It is reported as a histogram.

It will notably include the time spent to setup upstream subscriptions with appropriate transport for each source.

This metric tracks the duration of the complete GraphQL operation execution. It reports the time spent in the GraphQL specific processing, excluding the HTTP-level processing. It is reported as a histogram.

This metric provides a summary of the time spent on the GraphQL operation execution. It reports the same timing than graphql_envelop_request_duration but as a summary.

This metric tracks the number of errors that was returned by the GraphQL execution.

Similarly to graphql_gateway_subgraph_execute_errors, it counts all errors found in the final response constructed by the gateway after it gathered all subgraph responses, but it also includes errors from other GraphQL processing phases (parsing, validation and context building). It is exposed as a counter.

Depending on the phase when the error occurred, some labels may be missing. For example, if the error occurred during the context phase, only the phase label will be present.

This metric tracks the number of GraphQL operations executed. It counts all operations, either failed or successful, including subscriptions. It is exposed as a counter.

It can differ from the number reported by graphql_yoga_http_duration_sum because a single HTTP request can contain multiple GraphQL operations if batching has been enabled.

This metric tracks the number of deprecated fields used in the GraphQL operation.

This metric tracks the number of schema changes that have occurred since the gateway started. When polling is enabled, this will include the schema reloads.

If you are using a plugin that modifies the schema on the fly, be aware that this metric will also include updates made by those plugins. Which means that one schema update can actually trigger multiple schema changes.

This metric tracks the duration of each resolver execution. It reports the time spent only on additional resolvers, not on fields that are resolved by a subgraph. It is up to the subgraph server to implement resolver level metrics, the gateway can’t remotely track their execution time.

Filter resolvers to instrument

To mitigate the cost of instrumenting all resolvers, you can explicitly list the fields that should be instrumented by providing a list of field names to the instrumentResolvers option.

It is a list of strings in the form of TypeName.fieldName. For example, to instrument the hello root query, you would use Query.hello.

You can also use wildcards to instrument all the fields for a type. For example, to instrument all root queries, you would use Query.*.