semantic-conventions/docs/graphql/graphql-spans.md

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.

Attribute	Type	Description	Examples	Requirement Level	Stability
graphql.document	string	The GraphQL document being executed. [1]	query findBookById { bookById(id: ?) { name } }	Recommended
graphql.operation.name	string	The name of the operation being executed.	findBookById	Recommended
graphql.operation.type	string	The type of the operation being executed.	query; mutation; subscription	Recommended

[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.

Value	Description	Stability
mutation	GraphQL mutation
query	GraphQL query
subscription	GraphQL subscription