Errors and exceptions

as of v1.44.0

The two namespaces every other domain reaches for when a call fails, and the rules for recording them.

attributes: 6
metrics: 0
signals: 1
stable: 4
deprecated: 2

Signals

What this domain emits, and the attributes each one carries, most strongly required first. An attribute marked * is required on that signal; * is conditionally required.

Events 1

exceptionStableThis event describes a single exception.
exception.message*exception.type*exception.escapedexception.stacktrace

Specification

Eventsare bound by the logs specification — 162 requirements across 5 documents, 83 of them MUST or SHALL.

Requirements that name this domain 40

MUSTRecord ExceptionStable
The method MUST record an exception as an Event with the conventions outlined in the exceptions document.
MUSTRecord ExceptionStable
If RecordException is provided, the method MUST accept an optional parameter to provide any additional event attributes (this SHOULD be done in the same way as for the AddEvent method).
MUSTRecording an ExceptionStable
The name of the event MUST be "exception".
SHOULDRecord ExceptionStable
To facilitate recording an exception languages SHOULD provide a RecordException method if the language uses exceptions.
SHOULDRecord ExceptionStable
The minimum required argument SHOULD be no more than only an exception object.
SHOULDRecording an ExceptionStable
An exception SHOULD be recorded as an Event on the span during which it occurred if and only if it remains unhandled when the span ends and causes the span status to be set to ERROR.
MUST NOTBasic error handling principlesUnspecified
OpenTelemetry implementations MUST NOT throw unhandled exceptions at runtime.
MUST NOTBasic error handling principlesUnspecified
API methods MUST NOT throw unhandled exceptions when used incorrectly by end users.

All 40 matching requirements

On the wire, this lands in logs/v1/logs. Field-by-field definitions are under OTLP.

Attributes 6

exception4 attributes

exception.escaped
DeprecatedIndicates that the exception is escaping the scope of the span.
exception.message
StableThe exception message.
exception.stacktrace
StableA 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.type
StableThe 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 languag

error2 attributes

error.message
DeprecatedA message providing more detail about an error in human-readable form.
error.type
StableDescribes a class of error the operation ended with.

Recent changes

Breaking and notable changes to this domain across the last 6 semantic-conventions releases.

deprecatedattributeerror.messageUse domain-specific error message attribute. For example, use feature_flag.error.message for feature flag errors.

Topics are this site's grouping of upstream namespaces, not a structure the OpenTelemetry project publishes. JSON · All domains