Add OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN support to record_exception by RKest · Pull Request #5323 · open-telemetry/opentelemetry-python

RKest · 2026-06-18T12:38:34Z

Description

Span.record_exception currently always records exceptions as span
events. The semantic conventions for
exceptions in logs
and the span-event API deprecation plan
(OTEP 4430,
see also the
Deprecating Span Events
blog post) introduce the OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN environment
variable so instrumentations can migrate exceptions from span events to logs.

This PR makes the SDK's Span.record_exception (and therefore the
__exit__ / use_span paths that call it) honor
OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN:

Value	Behavior
(unset)	Span events only — existing behavior (default).
`logs`	Record the exception as a log only.
`logs/dup`	Record the exception as both a log and a span event (phased rollout).

Any unrecognized value is treated as unset, preserving today's behavior.

Implementation notes:

The exception log is emitted via the global LoggerProvider, correlated
with the originating span's context (trace_id / span_id), at ERROR
severity, with event_name="exception".
The log carries exception.type, exception.message and
exception.stacktrace. The deprecated exception.escaped attribute is
intentionally omitted from the log representation; it is still set on the
span event when one is recorded (logs/dup or default).
The log is emitted under the span's own instrumentation scope.
OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN is an experimental, transitional
opt-in, so it is kept private to opentelemetry.sdk.trace rather than
exported from opentelemetry.sdk.environment_variables.

The default behavior is unchanged, so this is fully backwards compatible and
opt-in.

Type of change

New feature (non-breaking change which adds functionality)

How Has This Been Tested?

A new test module opentelemetry-sdk/tests/trace/test_record_exception_logs.py
covers all modes end to end using an in-memory span exporter and a captured
logger:

unset / unrecognized values record a span event and emit no log
logs records a log only (no span event)
logs/dup records both a log and a span event
the emitted log is correlated with the originating span
(trace_id / span_id)
the log uses the span's instrumentation scope
exception.type / exception.message / exception.stacktrace are
populated and extra attributes are forwarded
the deprecated exception.escaped attribute is not set on the log

The existing record_exception tests in
opentelemetry-sdk/tests/trace/test_trace.py continue to pass unchanged.

uv run pytest opentelemetry-sdk/tests/trace/test_record_exception_logs.py
uv run pytest opentelemetry-sdk/tests/trace/test_trace.py -k record_exception

Does This PR Require a Contrib Repo Change?

Yes. - Link to PR:
No. The record_exception signature is unchanged; the new behavior is
gated behind an environment variable and defaults to today's behavior.

Checklist:

Followed the style guidelines of this project (ruff check / ruff format)
Changelogs have been updated (.changelog/5318.added — rename to match
the assigned PR number when opening the PR)
Unit tests have been added
Documentation has been updated (env var docstring + record_exception
docstring)

Copilot

Pull request overview

Adds opt-in support for recording exceptions as logs (and optionally duplicating to span events) in the SDK’s Span.record_exception, enabling migration away from span events per the exception-as-logs semantic conventions and the span-event deprecation plan.

Changes:

Update Span.record_exception to honor OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN and emit an exception LogRecord correlated with the span when configured.
Add end-to-end unit tests covering unset/unrecognized/logs/logs-dup behaviors, correlation, scope usage, and attribute mapping.
Add a changelog entry documenting the new opt-in behavior.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
opentelemetry-sdk/src/opentelemetry/sdk/trace/init.py	Adds env-var gated branching in `record_exception` and a helper to emit correlated exception logs.
opentelemetry-sdk/tests/trace/test_record_exception_logs.py	New tests validating exception-as-logs behavior across all opt-in modes.
.changelog/5318.added	Notes the new env-var controlled behavior for `Span.record_exception`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

`Span.record_exception` now honors the `OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN` environment variable, per the semantic conventions for exceptions in logs (https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-logs/): - unset: record exceptions as span events only (unchanged default) - `logs`: record exceptions as logs only - `logs/dup`: record exceptions as both logs and span events Exception logs are emitted at ERROR severity, correlated with the originating span's context, and use the span's instrumentation scope.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

RKest · 2026-07-06T15:14:18Z

@@ -1074,6 +1099,19 @@ def record_exception(
            if module and module != "builtins"
            else qualname
        )
+
+        signal = _exception_signal_opt_in()
+        if signal in (_EXCEPTION_SIGNAL_LOGS, _EXCEPTION_SIGNAL_LOGS_DUP):
+            self._record_exception_log(
+                exception_type=exception_type,


I'm thinking the _check_span_ended for exception logs is not necessary.

The check is likely for spans, because an ended span, might already be exported, so modifying it (through adding span events for example) should not be allowed.

Same constraint is not present in logs.

your reasoning makes sense to me

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

DylanRussell · 2026-07-08T18:24:59Z

+            LogRecord(
+                timestamp=timestamp if timestamp is not None else time_ns(),
+                context=trace_api.set_span_in_context(self),
+                event_name="exception",


https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-logs/#event-name -- should we allow an event name to be passed through here via record_exception ?

Same question about severity: https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-logs/#severity

RKest requested a review from a team as a code owner June 18, 2026 12:38

otelbot-python Bot added this to Python PR digest Jun 18, 2026

aabmass requested a review from Copilot June 24, 2026 20:05

Copilot started reviewing on behalf of aabmass June 24, 2026 20:05 View session

Copilot AI reviewed Jun 24, 2026

View reviewed changes

Comment thread opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py

Comment thread opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py Outdated

RKest force-pushed the record-exception-signal-opt-in branch from 828822d to e039edd Compare June 29, 2026 18:03

RKest requested a review from Copilot June 29, 2026 18:04

Copilot started reviewing on behalf of RKest June 29, 2026 18:05 View session

Copilot AI reviewed Jun 29, 2026

View reviewed changes

Comment thread opentelemetry-sdk/src/opentelemetry/sdk/trace/__init__.py Outdated

RKest force-pushed the record-exception-signal-opt-in branch from e039edd to 01425f1 Compare July 6, 2026 13:37

RKest requested a review from Copilot July 6, 2026 14:48

Copilot started reviewing on behalf of RKest July 6, 2026 14:51 View session

Copilot AI reviewed Jul 6, 2026

View reviewed changes

RKest requested a review from Copilot July 6, 2026 15:14

Copilot started reviewing on behalf of RKest July 6, 2026 15:15 View session

Copilot AI reviewed Jul 6, 2026

View reviewed changes

DylanRussell reviewed Jul 8, 2026

View reviewed changes

xrmx moved this to Reviewed PRs that need fixes in Python PR digest Jul 9, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN support to record_exception#5323

Add OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN support to record_exception#5323
RKest wants to merge 1 commit into
open-telemetry:mainfrom
RKest:record-exception-signal-opt-in

RKest commented Jun 18, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

RKest Jul 6, 2026 •

edited

Loading

Uh oh!

DylanRussell Jul 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

DylanRussell Jul 8, 2026

Uh oh!

DylanRussell Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

RKest commented Jun 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Does This PR Require a Contrib Repo Change?

Checklist:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

RKest Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DylanRussell Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

DylanRussell Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

DylanRussell Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

RKest commented Jun 18, 2026 •

edited

Loading

RKest Jul 6, 2026 •

edited

Loading