Observability

Observability support with Micrometer is directly instrumented in Spring for GraphQL. This enables both metrics and traces for GraphQL requests and "non-trivial" data fetching operations. Because the GraphQL engine operates on top of a transport layer, you should also expect observations from the transport, if supported in Spring Framework.

Observations are only published if an ObservationRegistry is configured in the application. You can learn more about configuring the observability infrastructure in Spring Boot. If you would like to customize the metadata produced with the GraphQL observations, you can configure a custom convention on the instrumentation directly. If your application is using Spring Boot, contributing the custom convention as a bean is the preferred way.

Server Requests instrumentation

GraphQL Server Requests observations are created with the name "graphql.request" for traditional and Reactive applications and above all supported transports. This instrumentation assumes that any parent observation must be set as the current one on the GraphQL context with the well-known "micrometer.observation" key. For trace propagation across network boundaries, a separate instrumentation at the transport level must be in charge. In the case of HTTP, Spring Framework has dedicated instrumentation that takes care of trace propagation.

Applications need to configure the org.springframework.graphql.observation.GraphQlObservationInstrumentation instrumentation in their application. It is using the org.springframework.graphql.observation.DefaultExecutionRequestObservationConvention by default, backed by the ExecutionRequestObservationContext.

By default, the following KeyValues are created:

Table 1. Low cardinality Keys

Name

Description

graphql.operation (required)

GraphQL Operation name.

graphql.outcome (required)

Outcome of the GraphQL request.

The graphql.operation KeyValue will use the custom name of the provided query, or the standard name for the operation if none ("query", "mutation" or "subscription"). The graphql.outcome KeyValue will be:

  • "SUCCESS" if a valid GraphQL response has been sent and it contains no errors

  • "REQUEST_ERROR" if the request could not be parsed, or if the response contains errors (none of them being of type org.springframework.graphql.execution.ErrorType.INTERNAL_ERROR)

  • "INTERNAL_ERROR" if no valid GraphQL response could be produced, or if the response contains at least one error of type org.springframework.graphql.execution.ErrorType.INTERNAL_ERROR

Table 2. High cardinality Keys

Name

Description

graphql.execution.id (required)

graphql.execution.ExecutionId of the GraphQL request.

Spring for GraphQL also contributes Events for Server Request Observations. Micrometer Observation Events are usually handled as span annotations in traces. This instrumentation records errors listed in the GraphQL response as events.

Table 3. Observation Events

Name

Contextual Name

the GraphQL error type, e.g. InvalidSyntax

the full GraphQL error message, e.g. "Invalid syntax with offending token 'invalid'…​"

DataFetcher instrumentation

GraphQL DataFetcher observations are created with the name "graphql.datafetcher", only for data fetching operations that are considered as "non trivial" (property fetching on a Java object is a trivial operation). Applications need to configure the org.springframework.graphql.observation.GraphQlObservationInstrumentation instrumentation in their application. It is using the org.springframework.graphql.observation.DefaultDataFetcherObservationConvention by default, backed by the DataFetcherObservationContext.

By default, the following KeyValues are created:

Table 4. Low cardinality Keys

Name

Description

graphql.error.type (required)

Class name of the data fetching error

graphql.field.name (required)

Name of the field being fetched.

graphql.outcome (required)

Outcome of the GraphQL data fetching operation, "SUCCESS" or "ERROR".
Table 5. High cardinality Keys

Name

Description

graphql.field.path (required)

Path to the field being fetched (for example, "/bookById").