Define FaaS exception event

.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

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:
 

docs/faas/faas-exceptions.md

@@ -0,0 +1,56 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Exceptions
+--->
+
+# Semantic conventions for FaaS exceptions
+
+**Status**: [Development][DocumentStatus]
+
+This document defines semantic conventions for recording exceptions on FaaS invocations.
+
+<!-- toc -->
+
+- [FaaS invocation exception](#faas-invocation-exception)
+
+<!-- tocstop -->
+
+## FaaS invocation exception
+
+<!-- semconv event.faas.invocation.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 `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.
+
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

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