Define gen_ai exception event for client operations

.chloggen/genai-exception-events.yaml

@@ -0,0 +1,8 @@
+change_type: enhancement
+component: gen-ai
+note: Define `gen_ai.client.operation.exception` event for recording exceptions during Generative AI client operations
+issues: [3436]
+subtext: |
+  This domain-specific exception event provides a structured way to record
+  exceptions that occur during Generative AI client operations (API errors,
+  rate limiting, timeouts).

docs/gen-ai/README.md

@@ -30,6 +30,7 @@ linkTitle: Generative AI
 Semantic conventions for Generative AI operations are defined for the following signals:
 
 * [Events](gen-ai-events.md): Semantic Conventions for Generative AI inputs and outputs - *events*.
+* [Exceptions](gen-ai-exceptions.md): Semantic Conventions for Generative AI *exceptions*.
 * [Metrics](gen-ai-metrics.md): Semantic Conventions for Generative AI operations - *metrics*.
 * [Model spans](gen-ai-spans.md): Semantic Conventions for Generative AI model operations - *spans*.
 * [Agent spans](gen-ai-agent-spans.md): Semantic Conventions for Generative AI agent operations - *spans*.

docs/gen-ai/gen-ai-exceptions.md

@@ -0,0 +1,56 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Exceptions
+--->
+
+# Semantic conventions for Generative AI exceptions
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for recording exceptions on Generative AI operations.
+
+<!-- toc -->
+
+- [Generative AI client operation exception](#generative-ai-client-operation-exception)
+
+<!-- tocstop -->
+
+## Generative AI client operation exception
+
+<!-- semconv event.gen_ai.client.operation.exception -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+
+**Status:** ![Development](https://img.shields.io/badge/-development-blue)
+
+The event name MUST be `gen_ai.client.operation.exception`.
+
+This event represents an exception that occurred during a Generative AI client operation, such as API errors, rate limiting, model errors, timeouts, or other errors that prevent the operation from completing successfully.
+
+This event SHOULD be recorded when an exception occurs during Generative AI client operations.
+Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event.
+Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding Generative AI client span.
+
+**Attributes:**
+
+| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
+| --- | --- | --- | --- | --- | --- |
+| [`exception.message`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [1] | string | The exception message. [2] | `Division by zero`; `Can't convert 'int' object to str implicitly` |
+| [`exception.type`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [3] | string | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. | `java.net.ConnectException`; `OSError` |
+| [`exception.stacktrace`](/docs/registry/attributes/exception.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` |
+
+**[1] `exception.message`:** Required if `exception.type` is not set, recommended otherwise.
+
+**[2] `exception.message`:**
+
+> [!WARNING]
+>
+> This attribute may contain sensitive information.
+
+**[3] `exception.type`:** Required if `exception.message` is not set, recommended otherwise.
+
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

model/gen-ai/events.yaml

@@ -44,3 +44,27 @@ groups:
           The `error.type` SHOULD match the error code returned by the Generative AI Evaluation provider or the client library,
           the canonical name of exception that occurred, or another low-cardinality error identifier.
           Instrumentations SHOULD document the list of errors they report.
+
+  - id: event.gen_ai.client.operation.exception
+    name: gen_ai.client.operation.exception
+    stability: development
+    type: event
+    brief: >
+      This event represents an exception that occurred during a Generative AI client operation,
+      such as API errors, rate limiting, model errors, timeouts, or other errors that prevent
+      the operation from completing successfully.
+    note: >
+      This event SHOULD be recorded when an exception occurs during Generative AI client operations.
+
+      Instrumentations SHOULD set the severity to WARN (severity number 13) when recording this event.
+
+      Instrumentations MAY provide a configuration option to populate exception events
+      with the attributes captured on the corresponding Generative AI client span.
+    attributes:
+      - ref: exception.type
+        requirement_level:
+          conditionally_required: Required if `exception.message` is not set, recommended otherwise.
+      - ref: exception.message
+        requirement_level:
+          conditionally_required: Required if `exception.type` is not set, recommended otherwise.
+      - ref: exception.stacktrace