Adds GraphQL Semantic Convention from Otel Workgroup

[PascalSenn]

Important

This is a working draft and is NOT intended to be merged yet. Final approval is still pending from both the OpenTelemetry Semantic Conventions maintainers and the GraphQL OpenTelemetry Working Group. This PR has been opened early to get feedback from the OTel side and be the base for discussion while the specification is being finalized.

Changes

This PR adds comprehensive GraphQL semantic conventions, developed by the GraphQL OpenTelemetry Working Group, to the OpenTelemetry Semantic Conventions repository.

Origin

This specification was developed in the graphql/graphql-wg otel-wg subcommittee over multiple working group sessions. Key contributors and participants include members from the GraphQL and OpenTelemetry communities working together to define instrumentation standards for GraphQL.

The specification intends to supersede the existing minimal GraphQL semantic conventions (previously only a single server span with 3 attributes) with a comprehensive convention covering the full GraphQL request lifecycle.

• Cardinality-safe by default: graphql.operation.name is opt-in on metrics; graphql.document.hash and graphql.document.id are preferred identifiers
• Phase-level observability: Separate spans and metrics for parse, validate, execute, and plan phases
• Federated/advanced server support: Step execution spans, operation planning, and source attributes for distributed GraphQL systems
• DataLoader support: Dedicated spans for batch operations with cache hit/miss tracking - Combined error+exception events: GraphQL errors caused by exceptions use a single event with both graphql.error.* and exception.* attributes
• Subscription support: Dedicated subscription event spans and active subscription
  metrics, distinct from request-level tracking

People involved

This work was developed by the GraphQL OpenTelemetry Working Group, a subcommittee of the GraphQL Working Group. Participants include representatives from across the GraphQL ecosystem working on instrumentation standards.

Important

The workgroup meets every third week of the month on thursday Checkout the calendar
In case you want to join add yourself to the agenda over at GraphQL OpenTelemetry Working Group

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• Links to the prototypes or existing instrumentations (when adding or changing conventions)

[github-actions]

This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:

• graphql

Such changes may be rejected or put on hold until a new SIG/project is established.

Please refer to the Semantic Convention Areas
document to see the current active SIGs and also to learn how to kick start a new one.

[github-actions]

This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:

• graphql

Such changes may be rejected or put on hold until a new SIG/project is established.

Please refer to the Semantic Convention Areas
document to see the current active SIGs and also to learn how to kick start a new one.

[PascalSenn]

@trask Can you let me know the process to get this reviewed?

[github-actions]

This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:

• graphql

Such changes may be rejected or put on hold until a new SIG/project is established.

Please refer to the Semantic Convention Areas
document to see the current active SIGs and also to learn how to kick start a new one.

[trask]

re-opening for discussion!

@PascalSenn also check out open-telemetry/opentelemetry-specification#4906

there has been quite a bit of progress since we discussed last year about the option of hosting semantic conventions outside of this repository. I think the work is pretty bleeding edge still but may be ready for external usage soon. In the meantime, let's review and discuss the GraphQL semantic conventions here.

[github-actions]

This PR has been labeled as stale due to lack of activity. It will be automatically closed if there is no further activity over the next 7 days.

[PascalSenn]

@thompson-tomo @trask can we reopen this PR?
I think there is only one comment left. I will present this to the TSC next week so hopefully we can get this in soon. (Ideally in the next couple of weeks)

[thompson-tomo]

Just a couple of small doc tweaks which will need a fresh markdown generated.