Adds GraphQL Semantic Convention from Otel Workgroup#3515
Conversation
|
This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:
Such changes may be rejected or put on hold until a new SIG/project is established. Please refer to the Semantic Convention Areas |
|
This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:
Such changes may be rejected or put on hold until a new SIG/project is established. Please refer to the Semantic Convention Areas |
|
@trask Can you let me know the process to get this reviewed? |
|
This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:
Such changes may be rejected or put on hold until a new SIG/project is established. Please refer to the Semantic Convention Areas |
|
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. |
|
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. |
…consistency - Updated error attributes in events.yaml to clarify the relationship between GraphQL-specific error details and exception information. - Renamed metrics in metrics.yaml for consistency, changing `active_requests` to `request.active`. - Revised registry.yaml to enhance attribute descriptions and examples, including the addition of `graphql.document.locations` and renaming selection attributes to field attributes. - Improved span definitions in spans.yaml to align with updated field naming conventions and clarified requirements for document IDs and hashes.
|
@thompson-tomo @trask can we reopen this PR? |
|
|
||
| **Span kind** SHOULD be `INTERNAL`. | ||
|
|
||
| **Attributes:** |
There was a problem hiding this comment.
would it be worth adding a graphql.subscription.event_count or something?
We're adding an option to let folks opt out of recording spans per subscription event. But it would still be useful to see high level rollups of events metrics. (Consider a case where subscriptions are used to implement streaming down individual characters in an LLM-generated response - would be many events/spans!)
There was a problem hiding this comment.
Further on this topic @PascalSenn has there been any discussion of using LogRecords per subscription event instead?
| This metric measures the end-to-end duration of processing a GraphQL | ||
| request on the server. It starts when the server begins processing | ||
| the GraphQL operation and ends when the response is complete. |
There was a problem hiding this comment.
One thing that could use clarification is around subscriptions. Would we expect this duration to express "the entire duration of a subscription" or "the duration between starting a subscription and the first subscription response"? Probably the answer to this has some implications for other subscription-related measurements.
There was a problem hiding this comment.
It's probably worth mirroring the http spec.
There were discussions here: open-telemetry/opentelemetry-specification#3520
There was a problem hiding this comment.
I would argue that the graphql.server span is currently specified incorrectly. In the case of SSE and WebSockets, the parent span, the HTTP root span, is also open for the entire duration of the subscription operation. If we want to align with HTTP, we should do the same.
This would also clarify the metric, since it would then represent the entire subscription duration. We could also add another span for the "subscribe" part of the subscription, but if we want to mirror the current HTTP behavior, then we should adjust the graphql.server span.
There was a problem hiding this comment.
Thanks for the updates. I'm good with this conceptually and appreciate the parity with HTTP / SSE / WebSockets. There may be performance implications which @BrynCooke could weigh in on (e.g. long-held memory allocations) but I'd say we should prefer to align with HTTP.
|
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. |
|
Any news on this feature ? Tks. |
|
@thompson-tomo can we reopen this - i try to resolve what's open this week |
|
@PascalSenn unfortunately i dont have permissions to. Ping @open-telemetry/specs-semconv-approvers @open-telemetry/specs-semconv-maintainers |
|
Here you go @PascalSenn |
…ion handling and remove deprecated metrics
|
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. |
Pull request dashboard statusStatus last refreshed: 2026-07-25 11:59:42 UTC.
This automated status or its linked feedback items may be incorrect. If something looks wrong, please report it with the result you expected. If you believe this pull request is incorrectly routed as waiting on the author, comment |
|
This is under review from the graphql foudnation side - so not stale |
9 participants
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.
graphql.operation.nameis opt-in on metrics;graphql.document.hashandgraphql.document.idare preferred identifiersgraphql.error.*andexception.*attributesmetrics, 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
[chore]