diff --git a/.chloggen/faas-exception-events.yaml b/.chloggen/faas-exception-events.yaml new file mode 100644 index 0000000000..30bc275ba9 --- /dev/null +++ b/.chloggen/faas-exception-events.yaml @@ -0,0 +1,8 @@ +change_type: enhancement +component: faas +note: Define domain-specific exception event for FaaS invocations +issues: [3451] +subtext: | + This domain-specific exception event provides a structured way to record + exceptions that occur during FaaS function invocations: + - `faas.invocation.exception` for exceptions during function execution diff --git a/docs/faas/README.md b/docs/faas/README.md index 69c59ee6af..3d35d0036f 100644 --- a/docs/faas/README.md +++ b/docs/faas/README.md @@ -12,6 +12,7 @@ Semantic conventions for FaaS are defined for the following signals: * [FaaS Spans](faas-spans.md): Semantic Conventions for FaaS *spans*. * [FaaS Metrics](faas-metrics.md): Semantic Conventions for FaaS *metrics*. +* [FaaS Exceptions](faas-exceptions.md): Semantic Conventions for FaaS *exceptions*. Technology specific semantic conventions are defined for the following FaaS services: diff --git a/docs/faas/faas-exceptions.md b/docs/faas/faas-exceptions.md new file mode 100644 index 0000000000..a467b2b601 --- /dev/null +++ b/docs/faas/faas-exceptions.md @@ -0,0 +1,56 @@ + + +# Semantic conventions for FaaS exceptions + +**Status**: [Development][DocumentStatus] + +This document defines semantic conventions for recording exceptions on FaaS invocations. + + + +- [FaaS invocation exception](#faas-invocation-exception) + + + +## FaaS invocation exception + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +The event name MUST be `faas.invocation.exception`. + +This event represents an exception that occurred during FaaS function invocation, such as application errors, internal failures, or other exceptions that prevent the function from completing successfully. + +This event SHOULD be recorded when an exception occurs during FaaS function invocation. +Instrumentations SHOULD set the severity to ERROR (severity number 17) when recording this event. +Instrumentations MAY provide a configuration option to populate exception events with the attributes captured on the corresponding FaaS 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/faas/events.yaml b/model/faas/events.yaml new file mode 100644 index 0000000000..5949f8c03a --- /dev/null +++ b/model/faas/events.yaml @@ -0,0 +1,24 @@ +groups: + - id: event.faas.invocation.exception + name: faas.invocation.exception + stability: development + type: event + brief: > + This event represents an exception that occurred during FaaS function invocation, + such as application errors, internal failures, or other exceptions that prevent + the function from completing successfully. + note: > + This event SHOULD be recorded when an exception occurs during FaaS function invocation. + + Instrumentations SHOULD set the severity to ERROR (severity number 17) when recording this event. + + Instrumentations MAY provide a configuration option to populate exception events + with the attributes captured on the corresponding FaaS 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