diff --git a/spec/registry.yaml b/spec/registry.yaml index 27fdf28..f1e7403 100644 --- a/spec/registry.yaml +++ b/spec/registry.yaml @@ -88,3 +88,47 @@ groups: note: > The coordinate follows the format "{ParentType}.{fieldName}" and uniquely identifies the field within the GraphQL schema. + - id: graphql.dataloader.name + brief: "The name of the DataLoader instance." + type: string + stability: development + examples: ["UserLoader", "ProductByIdLoader", "CommentsByPostIdLoader"] + note: > + This represents the name or identifier of the DataLoader instance. + When the DataLoader implementation supports naming, this SHOULD be set. + This helps in identifying specific DataLoader instances in observability. + - id: graphql.dataloader.batch.size + brief: "The number of individual requests in the DataLoader batch." + type: int + stability: development + examples: [5, 12, 25] + note: > + This represents the total number of individual load requests that were + batched together in a single batch operation. This includes both cache + hits and cache misses. + - id: graphql.dataloader.batch.keys + brief: "A subset of the keys requested in the DataLoader batch." + type: string[] + stability: development + examples: [["user:1", "user:2", "user:3"], ["post:42", "post:99"]] + note: > + This attribute is opt-in and SHOULD NOT be enabled by default, as keys + may contain sensitive or high-cardinality data. When enabled, implementations + MAY truncate the list to a configurable maximum number of keys. + The string representation of each key depends on the DataLoader implementation. + - id: graphql.dataloader.cache.hit_count + brief: "The number of requests in the batch that were served from the DataLoader cache." + type: int + stability: development + examples: [0, 3, 10] + note: > + This represents the number of individual load requests that were + resolved from the DataLoader's cache without requiring a fetch. + - id: graphql.dataloader.cache.miss_count + brief: "The number of requests in the batch that required fetching." + type: int + stability: development + examples: [2, 5, 12] + note: > + This represents the number of individual load requests that were + not found in the DataLoader's cache and required a fetch operation. diff --git a/spec/spans.yml b/spec/spans.yml index 3631ab2..af31d3b 100644 --- a/spec/spans.yml +++ b/spec/spans.yml @@ -175,3 +175,60 @@ groups: requirement_level: required - ref: graphql.selection.field.coordinate requirement_level: required + + - id: span.graphql.server.dataloader.dispatch + type: span + stability: development + span_kind: internal + brief: > + This optional span groups all DataLoader batch operations for a given request. + note: | + **Span name** SHOULD be `GraphQL DataLoader Dispatch`. + + This span is OPTIONAL. When present, it acts as a grouping span for all + DataLoader batch spans within a single GraphQL request. It represents + the overall dispatch of DataLoader batch operations. + + The span SHOULD be a child of the `graphql.server.request` span. + + Instrumentations that do not produce this span SHOULD attach DataLoader + batch spans directly to the `graphql.server.request` span or to the + resolver execution span that triggered the batch dispatch. + attributes: [] + + - id: span.graphql.server.dataloader.batch + type: span + stability: development + span_kind: internal + brief: > + This span represents the execution of a DataLoader batch operation. + note: | + **Span name** SHOULD be `GraphQL DataLoader Batch {dataloader.name}` when + the DataLoader has a name, otherwise `GraphQL DataLoader Batch`. + + This span covers the batched execution of multiple individual DataLoader + requests. It represents the time from when the batch is scheduled to + when all results are available. This span is created when a DataLoader + batches multiple individual load requests into a single batch operation + to optimize data access patterns. + + The parent of this span depends on what the instrumentation supports: + - If the `graphql.server.dataloader.dispatch` span is present, + this span SHOULD be a child of it. + - Otherwise, this span SHOULD be a child of the `graphql.server.request` + span, or of the resolver execution span that triggered the batch dispatch. + + The span SHOULD have links to all resolver execution spans that + contributed load requests to this batch, so that the causal + relationship between resolvers and the batch is preserved. + attributes: + - ref: graphql.dataloader.name + requirement_level: recommended + - ref: graphql.dataloader.batch.size + requirement_level: required + - ref: graphql.dataloader.batch.keys + requirement_level: opt_in + - ref: graphql.dataloader.cache.hit_count + requirement_level: opt_in + - ref: graphql.dataloader.cache.miss_count + requirement_level: opt_in