Adds initial otel spec documents #32

PascalSenn · 2025-08-07T19:25:02Z

No description provided.

PascalSenn · 2025-08-07T19:59:15Z

spec/registry.yaml

+        brief: "The path of the selection that is being resolved."
+        type: string
+        stability: development
+        examples: ["/persons/0/address", "person[0].address"]


We have to settle here on 1 format

Given the only mention of "path" in the spec defines it as a heterogenous array of strings and integers, and that JSON is documented as the most common serialization format, I'm inclined to prefer the bracket notation option.

marcotc

Awesome work, @PascalSenn! 🙇

spec/registry.yaml

marcotc · 2025-08-25T21:26:19Z

spec/spans.yml

+      For persisted operations with a specified operation name, instrumentations 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 and the operation is successfully identified
+      in the document.
+
+      > **Warning**
+      > The `graphql.operation.name` value is provided by the client and can have high
+      > cardinality. Using it in the GraphQL server span name is NOT RECOMMENDED for
+      > ad-hoc operations without careful consideration of cardinality implications.
+      > For persisted operations, the cardinality is bounded and using the operation
+      > name in the span name is more acceptable.


Suggested change

For persisted operations with a specified operation name, instrumentations 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 and the operation is successfully identified

in the document.

> **Warning**

> The `graphql.operation.name` value is provided by the client and can have high

> cardinality. Using it in the GraphQL server span name is NOT RECOMMENDED for

> ad-hoc operations without careful consideration of cardinality implications.

> For persisted operations, the cardinality is bounded and using the operation

> name in the span name is more acceptable.

For operation domains with bounded cardinality, instrumentations MAY provide

a configuration option to enable a more descriptive span name following the

`{graphql.operation.type} {graphql.operation.name}` format when

`graphql.operation.name` is available and the operation is successfully identified

in the document.

> **Warning**

> The `graphql.operation.name` value is provided by the client and can have high

> cardinality. Using it in the GraphQL server span name is NOT RECOMMENDED for

> ad-hoc operations without careful consideration of cardinality implications.

> For persisted operations or internal GraphQL APIs, the cardinality is bounded and using the operation

> name in the span name is more acceptable.

I think it's clearer to focus on the condition causing the risk (cardinality), and use "persisted operations" only only exemplify, instead of leading with "persisted operations", as one could interpret "persisted operations" as being the main deciding factor that applies here.

exclude automated persisted queries

spec/spans.yml

marcotc · 2025-08-25T21:57:31Z

spec/registry.yaml

+        brief: "The path of the selection that is being resolved."
+        type: string
+        stability: development
+        examples: ["/persons/0/address", "person[0].address"]


Given the only mention of "path" in the spec defines it as a heterogenous array of strings and integers, and that JSON is documented as the most common serialization format, I'm inclined to prefer the bracket notation option.

ravangen

Exciting to see this come together!

ravangen · 2025-08-28T18:42:35Z

spec/registry.yaml

+              stability: development
+        examples: ["query", "mutation", "subscription"]
+      - id: graphql.operation.hash
+        brief: "The hash of the operation document."


If a server was to generate a normalized hash/signature (example), do you imagine that would be a separate attribute? Is that worth mentioning? At first glance I took this to be a hash of the original raw document.

From [RFC] Add Appendix A: Persisted Documents, the sentiment so far is that the hash is created from the raw document, as even small modifications (e.g. removing whitespaces) can change error locations and confuse clients.

That being said, there's quite a bit being discussed in that RFC (e.g. what exactly the hash prefix, the part before :, means and its semantics) that it makes me think that we can either: follow that "Persisted Documents RFC"s guidance in its current state; delay the introduction of fields related to persisted queries until that RFC is published or at least closer to being published.

Regarding the Operation Signature, I think it is a useful data point but I'm not sure if we want to commit to adding this concept at this time.

That is fair and is less of a concern to internal APIs. Using the original document makes sense.

For us, we have two hashes but that doesn't mean we need to have it in a spec.

spec/spans.yml

Co-authored-by: Marco Costa <[email protected]>

PascalSenn · 2025-08-07T20:01:10Z

spec/registry.yaml

+        examples: ["/persons/0/address", "person[0].address"]
+        note: >
+          The path represents the location of the field being resolved within the result structure.
+          Path format may vary between implementations but SHOULD be consistent within an implementation.


Suggested change

Path format may vary between implementations but SHOULD be consistent within an implementation.

PascalSenn · 2025-08-28T17:29:44Z

spec/spans.yml

+      For persisted operations with a specified operation name, instrumentations 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 and the operation is successfully identified
+      in the document.
+
+      > **Warning**
+      > The `graphql.operation.name` value is provided by the client and can have high
+      > cardinality. Using it in the GraphQL server span name is NOT RECOMMENDED for
+      > ad-hoc operations without careful consideration of cardinality implications.
+      > For persisted operations, the cardinality is bounded and using the operation
+      > name in the span name is more acceptable.


exclude automated persisted queries

spec/spans.yml

EmrysMyrddin · 2025-09-12T12:13:31Z

spec/registry.yaml

+        stability: development
+        examples: ["person[0].address"]
+        note: >
+          The path represents the location of the field being resolved within the result structure.


Should we also add the precision here about field aliasing?
It is implicit that the path should always use aliased field name if any, but should we make it explicit ?

Suggested change

The path represents the location of the field being resolved within the result structure.

The path represents the location of the field being resolved within the result structure. If a field in the path has an alias, it SHOULD be used, otherwise the field name is used.

EmrysMyrddin · 2025-09-12T12:18:18Z

spec/spans.yml

@@ -0,0 +1,177 @@
+groups:
+  - id: span.graphql.server.request


In the description, we are talking about a Graphql Operation.
Should the id be span.graphql.server.operation instead of request ? It would also help to avoid the confusion between the transport (an HTTP request for example) and the actual operation.

EmrysMyrddin · 2025-09-12T12:19:11Z

spec/spans.yml

+    stability: development
+    span_kind: server
+    brief: >
+      This span represents an incoming GraphQL request on a server implementation.


Same thing here, if you agree with the previous comment.

Suggested change

This span represents an incoming GraphQL request on a server implementation.

This span represents an incoming GraphQL operation on a server implementation.

EmrysMyrddin · 2025-09-12T12:24:39Z

spec/spans.yml

+          conditionally_required: If parsing succeeded
+      - ref: graphql.operation.name
+        requirement_level:
+          conditionally_required: If available and not empty.


So this means it is optional (but allowed) to include this attribute when the operation name is not available in the document?

Adds initial otel spec documents

5f2663d

PascalSenn commented Aug 7, 2025

View reviewed changes

PascalSenn added 4 commits August 7, 2025 22:01

cleanup

a3130be

cleanup

9d5df68

improve resolver execution

fbe883d

change the name of the resolver span

4d9fa6c

marcotc reviewed Aug 25, 2025

View reviewed changes

ravangen reviewed Aug 28, 2025

View reviewed changes

PascalSenn and others added 2 commits August 28, 2025 22:31

Align with what we have discussed in the wg

10bc3bb

change from @marcotc

59341b7

Co-authored-by: Marco Costa <[email protected]>

PascalSenn commented Aug 31, 2025

View reviewed changes

EmrysMyrddin reviewed Sep 12, 2025

View reviewed changes

	The path represents the location of the field being resolved within the result structure.
	The path represents the location of the field being resolved within the result structure. If a field in the path has an alias, it SHOULD be used, otherwise the field name is used.

	This span represents an incoming GraphQL request on a server implementation.
	This span represents an incoming GraphQL operation on a server implementation.

Adds initial otel spec documents #32

Are you sure you want to change the base?

Adds initial otel spec documents #32

Uh oh!

Conversation

PascalSenn commented Aug 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marcotc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ravangen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants