Add OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN support to record_exception

[RKest]

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.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[github-actions]

This PR has been automatically marked as stale because it has not had any activity for 14 days. It will be closed if no further activity occurs within 14 days of this comment.
If you're still working on this, please add a comment or push new commits.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on maintainers · refreshed 2026-08-24 18:33 UTC

Merge when ready.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

[lzchen]

Don't we need to change the api to accept these new params as well?

[RKest]

Yes, great point.

I added these, as default-None, to not pull in SeverityNumber (outside of if TYPE_CHECKING) from unstable _logs module, into the stable trace one. Meaningful defaults are set in the SDK only.

This does make current Span implementations incompatible according to some linters, but there have been prior similar changes, so I don't think this constitutes a breaking change.

I verified there was a similar change to this one, which was not in-fact marked as a breaking change: https://github.com/open-telemetry/opentelemetry-python/pull/4028/changes

[lzchen]

I believe the old self.add_event() is a noop if the span has ended already. Should we do the same check here?

[RKest]

I added a guard. However, unlike add_event, this one is not inside a lock, because a lock in this case would potentially block span.end() on synchronous log export (which I believe is not unacceptable?).

Only drawback here is a possible race condition, where log export can happen after the span has ended.

This should be okay, because AFAIU the guard should protect against egregious developer mistakes, where a log truly has no business being attached to a long ended span, in which case this race condition would be tolerable. Also unlike adding span events, logs export still functions even after the span ends (and is exported) so I think this minor lack of parity is okay.