c55de8d091
Prior to this commit, GraphQL Request Observations would not record errors as Observation errors, because with GraphQL errors can partially affect the response and there can be multiple. Instead, an invalid request (for example) would lead to a `"graphql.outcome", "REQUEST_ERROR"` low cardinality KeyValue. In this case, developers would not know what type of error occured nor if there were multiple. This commit records all errors listed in the GraphQL as Observation.Event on the request Observation. Such events are usually handled by the tracing handler and are recorded as span annotations for traces. Other `ObservationHandler` annotations can leverage events in a different fashion. Closes gh-859
80 lines
4.5 KiB
Plaintext
80 lines
4.5 KiB
Plaintext
[[observability]]
|
|
= Observability
|
|
|
|
https://micrometer.io/docs/observation[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 {spring-framework-ref-docs}/integration/observability.html[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 {spring-boot-ref-docs}/actuator.html#actuator.metrics[configuring the observability infrastructure in Spring Boot].
|
|
If you would like to customize the metadata produced with the GraphQL observations, you can {spring-framework-ref-docs}/integration/observability.html#observability.config.conventions[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.
|
|
|
|
[[observability.server.request]]
|
|
== 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 {spring-framework-ref-docs}/integration/observability.html#observability.http-server[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:
|
|
|
|
.Low cardinality Keys
|
|
[cols="a,a"]
|
|
|===
|
|
|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 http://spec.graphql.org/draft/#sec-Language.Operations[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, `"REQUEST_ERROR"` if the request could not be parsed, or `"INTERNAL_ERROR"` if no valid GraphQL response could be produced.
|
|
|
|
.High cardinality Keys
|
|
[cols="a,a"]
|
|
|===
|
|
|Name | Description
|
|
|`graphql.execution.id` _(required)_|`graphql.execution.ExecutionId` of the GraphQL request.
|
|
|===
|
|
|
|
Spring for GraphQL also contributes Events for Server Request Observations.
|
|
https://docs.micrometer.io/micrometer/reference/observation/components.html#micrometer-observation-events[Micrometer Observation Events] are usually handled as span annotations in traces.
|
|
This instrumentation records errors listed in the GraphQL response as events.
|
|
|
|
.Observation Events
|
|
[cols="a,a"]
|
|
|===
|
|
|Name | Contextual Name
|
|
|the GraphQL error type, e.g. `InvalidSyntax`|the full GraphQL error message, e.g. `"Invalid syntax with offending token 'invalid'..."`
|
|
|===
|
|
|
|
|
|
[[observability.server.datafetcher]]
|
|
== 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:
|
|
|
|
.Low cardinality Keys
|
|
[cols="a,a"]
|
|
|===
|
|
|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".
|
|
|===
|
|
|
|
|
|
.High cardinality Keys
|
|
|===
|
|
|Name | Description
|
|
|`graphql.field.path` _(required)_|Path to the field being fetched (for example, "/bookById").
|
|
|===
|