Semantic conventions for GraphQL server spans
April 20, 2026 ยท View on GitHub
Status: Development
Status:
This span represents an incoming operation on a GraphQL server implementation.
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.
Span kind SHOULD be SERVER.
Span status SHOULD follow the Recording Errors document.
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
graphql.operation.name |  | Recommended | string | The name of the operation being executed. | findBookById |
graphql.operation.type | | Recommended | string | The type of the operation being executed. | query; mutation; subscription |
graphql.document | | Opt-In | string | The GraphQL document being executed. [1] | query findBookById { bookById(id: ?) { name } } |
[1] graphql.document: If instrumentation can reliably identify and redact sensitive information it SHOULD do it.
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 | |