# Semantic conventions for exceptions on spans

**Status**: [Deprecated][DocumentStatus]<br>
Use [Semantic conventions for exceptions in logs](exceptions-logs.md) instead.

This document defines semantic conventions for recording application
exceptions associated with spans.


> [!IMPORTANT]
>
> Existing instrumentations that record exceptions as span events:
>
> * SHOULD introduce an environment variable `OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN`
>   supporting the following values:
>   * `logs` - emit exceptions as logs only.
>   * `logs/dup` - emit both span events and logs, allowing for a phased rollout.
>   * The default behavior (in the absence of one of these values) is to continue
>     emitting exceptions as span events (existing behavior).
> * SHOULD maintain (security patching at a minimum) their existing major version
>   for at least six months after it starts emitting both sets of conventions.
> * MAY drop the environment variable in their next major version and emit exceptions
>   as logs only.
>
> Even after instrumentations start emitting exceptions only as logs, users will
> still have the option to route those to span events at the SDK layer.

## Exception event

<!-- semconv event.exception -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen)

The event name MUST be `exception`.

This event describes a single exception.

**Attributes:**

| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`exception.message`](/docs/specs/semconv/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/specs/semconv/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.escaped`](/docs/specs/semconv/registry/attributes/exception.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>It's no longer recommended to record exceptions that are handled and do not escape the scope of a span. | `Recommended` | boolean | Indicates that the exception is escaping the scope of the span. | |
| [`exception.stacktrace`](/docs/specs/semconv/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 -->

### Stacktrace representation

The table below, adapted from [Google Cloud][gcp-error-reporting], includes
possible representations of stacktraces in various languages. The table is not
meant to be a recommendation for any particular language, although SIGs are free
to adopt them if they see fit.

| Language   | Format                                                             |
| ---------- | ------------------------------------------------------------------ |
| C#         | the return value of [Exception.ToString()][csharp-stacktrace]      |
| Elixir     | the return value of [Exception.format/3][elixir-stacktrace]        |
| Erlang     | the return value of [`erl_error:format`][erlang-stacktrace]        |
| Go         | the return value of [runtime.Stack][go-stacktrace]                 |
| Java       | the contents of [Throwable.printStackTrace()][java-stacktrace]     |
| Javascript | the return value of [error.stack][js-stacktrace] as returned by V8 |
| Python     | the return value of [traceback.format_exc()][python-stacktrace]    |
| Ruby       | the return value of [Exception.full_message][ruby-full-message]    |

Backends can use the language specified methodology for generating a stacktrace
combined with platform information from the
[telemetry sdk resource][telemetry-sdk-resource] in order to extract more fine
grained information from a stacktrace, if necessary.

[gcp-error-reporting]: https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report
[java-stacktrace]: https://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html#printStackTrace%28%29
[python-stacktrace]: https://docs.python.org/3/library/traceback.html#traceback.format_exc
[js-stacktrace]: https://v8.dev/docs/stack-trace-api
[ruby-full-message]: https://docs.ruby-lang.org/en/3.4/Exception.html#method-i-full_message
[csharp-stacktrace]: https://docs.microsoft.com/dotnet/api/system.exception.tostring
[go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack
[telemetry-sdk-resource]: ../resource/README.md#telemetry-sdk
[erlang-stacktrace]: https://www.erlang.org/doc/apps/stdlib/erl_error.html#format_exception/3
[elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3
[DocumentStatus]: /docs/specs/otel/document-status