Cleanup specification for submit

spec/events.yaml

@@ -15,10 +15,39 @@ groups:
       When the response contains both `data` and `errors` (partial success),
       the severity SHOULD be WARN (severity number 13). When the response
       contains only `errors` and no `data` (complete failure), the severity
-      SHOULD be ERROR (severity number 17).
+      SHOULD be ERROR (severity number 17). When severity cannot be determined,
+      instrumentations SHOULD default to ERROR.
 
-      Errors and exceptions can coexist for the same issue - errors being visible
-      to users and exceptions representing unhandled issues with stack traces.
+      **GraphQL errors and exceptions:**
+      When a GraphQL error is caused by an underlying exception, instrumentations
+      SHOULD record both the GraphQL error details and the exception information
+      on the same `graphql.error` event rather than emitting separate events.
+      The exception attributes (`exception.type`, `exception.message`,
+      `exception.stacktrace`) MAY be included alongside the `graphql.error.*`
+      attributes on the same event. This avoids duplicate events for the same
+      underlying issue and keeps the error context together.
+
+      When a GraphQL error is NOT caused by an exception (e.g., validation errors,
+      authorization errors returned by the GraphQL layer), only the `graphql.error.*`
+      attributes are needed.
+
+      Instrumentations SHOULD cap the number of error events per span to a configurable
+      maximum (default: 10) to prevent excessive telemetry. When capped, the total error
+      count SHOULD still be recorded via `graphql.error.count` on the parent span.
+
+      **Relationship to span status and `error.type`:**
+      GraphQL error events provide detailed per-error information from the response `errors`
+      array. They are complementary to span-level error signals:
+
+      - `error.type` on the parent span provides a low-cardinality error classification
+        for the overall operation outcome. It SHOULD be set based on the `graphql.error.code`
+        of the first error or a general error category.
+      - Individual `graphql.error` events provide the structured details for each error
+        in the response.
+
+      Instrumentations SHOULD set both `error.type` on the span and emit error events
+      for each error in the response. The error events provide the detail; `error.type`
+      and span status provide the summary.
     attributes:
       - ref: graphql.error.message
         requirement_level: required
@@ -30,6 +59,38 @@ groups:
           conditionally_required: Must be included when the error can be associated with a particular field in the GraphQL result.
       - ref: graphql.error.code
         requirement_level: opt_in
+      - ref: exception.type
+        requirement_level:
+          conditionally_required: If the error was caused by an exception.
+        note: >
+          The fully qualified class name or type of the exception that caused
+          this GraphQL error, when applicable.
+      - ref: exception.message
+        requirement_level:
+          conditionally_required: If the error was caused by an exception.
+        note: >
+          The exception message. When both `graphql.error.message` and
+          `exception.message` are available, both SHOULD be set as they
+          may differ (the GraphQL error message is user-facing, while the
+          exception message is the raw internal error).
+      - ref: exception.stacktrace
+        requirement_level: opt_in
+        note: >
+          The exception stacktrace, when available and the error was caused
+          by an exception. This attribute is opt-in due to its size and
+          potential to contain sensitive information.
       - ref: graphql.error.schema_coordinate
         requirement_level:
           conditionally_required: Should be included when the error can be associated with a particular field in the GraphQL schema.
+      - ref: graphql.operation.type
+        requirement_level: recommended
+        note: >
+          Including the operation type on error events enables correlation and filtering
+          of errors by operation type without requiring access to the parent span.
+      - ref: graphql.operation.name
+        requirement_level:
+          conditionally_required: If available and not empty.
+        note: >
+          Including the operation name on error events enables correlation of errors
+          to specific operations, especially useful when error events are processed
+          independently of spans (e.g., in log-based pipelines).