# Semantic conventions for GraphQL server spans

LLMS index: [llms.txt](/llms.txt)

---

**Status**: [Development][DocumentStatus]

<!-- semconv span.graphql.server -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

**Status:** ![Development](https://img.shields.io/badge/-development-blue)

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](/docs/specs/semconv/general/recording-errors.md) document.

**Attributes:**

| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`graphql.document`](/docs/specs/semconv/registry/attributes/graphql.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The GraphQL document being executed. [1] | `query findBookById { bookById(id: ?) { name } }` |
| [`graphql.operation.name`](/docs/specs/semconv/registry/attributes/graphql.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The name of the operation being executed. | `findBookById` |
| [`graphql.operation.type`](/docs/specs/semconv/registry/attributes/graphql.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The type of the operation being executed. | `query`; `mutation`; `subscription` |

**[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 | ![Development](https://img.shields.io/badge/-development-blue) |
| `query` | GraphQL query | ![Development](https://img.shields.io/badge/-development-blue) |
| `subscription` | GraphQL subscription | ![Development](https://img.shields.io/badge/-development-blue) |

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

[DocumentStatus]: /docs/specs/otel/document-status