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 MUST be of the format <graphql.operation.type> <graphql.operation.name> provided that graphql.operation.type and graphql.operation.name are available. If graphql.operation.name is not available, the span SHOULD be named <graphql.operation.type>. When <graphql.operation.type> is not available, GraphQL Operation MAY be used as span name.

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]: 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