# Semantic conventions for exceptions in logs

LLMS index: [llms.txt](/llms.txt)

---

**Status**: [Stable][DocumentStatus]

This document defines semantic conventions for recording exceptions on
[logs](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.54.0/specification/logs/api.md#emit-a-logrecord)
emitted through the [Logger API](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.54.0/specification/logs/api.md#logger).


> [!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.

## Recording an exception

Exceptions SHOULD be recorded as attributes on the
[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.54.0/specification/logs/data-model.md#log-and-event-record-definition) passed to the [Logger](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.54.0/specification/logs/api.md#logger) emit
operations. Exceptions MAY be recorded on "logs" or "events" depending on the
context.

To encapsulate proper handling of exceptions API authors MAY provide a
constructor, `RecordException` method/extension, or similar helper mechanism on
the `LogRecord` class/structure or wherever it makes the most sense depending on
the language runtime.

## Attributes

The table below indicates which attributes should be added to the
[LogRecord](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.54.0/specification/logs/data-model.md#log-and-event-record-definition) and their types.

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

**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.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

Same as [Trace Semantic Conventions for Exceptions - Stacktrace
Representation](exceptions-spans.md#stacktrace-representation).

[DocumentStatus]: /docs/specs/otel/document-status