Semantic Conventions for GraphQL Server

Status: Experimental

This document defines semantic conventions to apply when instrumenting the GraphQL implementation. They map GraphQL operations to attributes on a Span.

The span name SHOULD be of the format {graphql.operation.type} provided graphql.operation.type is available. If graphql.operation.type is not available, the span SHOULD be named GraphQL Operation.

Warning The graphql.operation.name value is provided by the client and can have high cardinality. Using it in the GraphQL server span name (by default) is NOT RECOMMENDED.

Instrumentation MAY provide a configuration option to enable a more descriptive span name following {graphql.operation.type} {graphql.operation.name} format when graphql.operation.name is available.

AttributeTypeDescriptionExamplesRequirement LevelStability
graphql.documentstringThe GraphQL document being executed. [1]query findBookById { bookById(id: ?) { name } }RecommendedExperimental
graphql.operation.namestringThe name of the operation being executed.findBookByIdRecommendedExperimental
graphql.operation.typestringThe type of the operation being executed.query; mutation; subscriptionRecommendedExperimental

[1] graphql.document: The value may be sanitized to exclude sensitive information.


graphql.operation.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
mutationGraphQL mutationExperimental
queryGraphQL queryExperimental
subscriptionGraphQL subscriptionExperimental