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.

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