diff --git a/.chloggen/genai-exception-events.yaml b/.chloggen/genai-exception-events.yaml new file mode 100644 index 0000000000..8ffdf83e41 --- /dev/null +++ b/.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). diff --git a/docs/gen-ai/README.md b/docs/gen-ai/README.md index 69f056d87b..d509d65215 100644 --- a/docs/gen-ai/README.md +++ b/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*. diff --git a/docs/gen-ai/gen-ai-exceptions.md b/docs/gen-ai/gen-ai-exceptions.md new file mode 100644 index 0000000000..e71f36d495 --- /dev/null +++ b/docs/gen-ai/gen-ai-exceptions.md @@ -0,0 +1,56 @@ + + +# Semantic conventions for Generative AI exceptions + +**Status**: [Development][DocumentStatus] + +This document defines semantic conventions for recording exceptions on Generative AI operations. + + + +- [Generative AI client operation exception](#generative-ai-client-operation-exception) + + + +## Generative AI client operation exception + + + + + + +**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. + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/gen-ai/events.yaml b/model/gen-ai/events.yaml index 40b4051640..ce86109a6d 100644 --- a/model/gen-ai/events.yaml +++ b/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