Skip to content

Update exception recording guidelines to not use span events#3256

Merged
lmolkova merged 30 commits intoopen-telemetry:mainfrom
pellared:rem-span-events
Jan 28, 2026
Merged

Update exception recording guidelines to not use span events#3256
lmolkova merged 30 commits intoopen-telemetry:mainfrom
pellared:rem-span-events

Conversation

@pellared
Copy link
Member

@pellared pellared commented Jan 7, 2026

Together with open-telemetry/opentelemetry-specification#4825

Towards OTEP: Span Event API deprecation plan

Towards open-telemetry/opentelemetry-go-contrib#8386 (merged "prototype")

Changes

  • Remove the recommendation to use Span.RecordException for error recording
  • Update the recording exception example to record logs and metrics.
  • Deprecate "Semantic conventions for exceptions on spans" document in favor of logs for recording exceptions

@github-actions github-actions bot added the enhancement New feature or request label Jan 7, 2026
@github-actions

This comment was marked as duplicate.

@github-actions

This comment was marked as duplicate.

@pellared pellared reopened this Jan 7, 2026
@github-actions

This comment was marked as duplicate.

@github-actions

This comment was marked as duplicate.

@github-actions

This comment was marked as duplicate.

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the OpenTelemetry semantic conventions to deprecate recording exceptions as span events in favor of using log records. This change aligns with OTEP 4430's Span Event API deprecation plan and provides clearer guidance on exception handling across different signals.

Key changes:

  • Deprecates the event.exception convention, marking it as obsoleted with guidance to use logs instead
  • Updates error recording guidelines to recommend logging exceptions rather than using Span.recordException API
  • Revises the code example to demonstrate proper exception recording using logger APIs along with span status and metrics

Reviewed changes

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

Show a summary per file
File Description
model/exceptions/deprecated/events-deprecated.yaml Adds deprecation metadata to the exception event, marking it as obsoleted with a note to use logs
docs/general/recording-errors.md Updates exception recording section to recommend logs over span events and revises the code example to demonstrate logger usage
docs/exceptions/exceptions-spans.md Updates status badge from Stable to Deprecated with explanatory note
.github/copilot-instructions.md Updates internal guidelines to reflect that exceptions should be recorded as log records only
.chloggen/3256.yaml Adds changelog entry for the exception recording guideline update

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
@pellared pellared marked this pull request as ready for review January 7, 2026 22:34
@lmolkova lmolkova moved this from Untriaged to Needs More Approval in Semantic Conventions Triage Jan 25, 2026
Co-authored-by: Liudmila Molkova <neskazu@gmail.com>
@pellared pellared requested a review from trask January 27, 2026 18:02
@pellared
Copy link
Member Author

@lmolkova, @trask, PTAL
I tried to make it as minimal as possible to avoid more bike-shedding. I still think that there are things that has to be improved like when an exception is not an error. But it deserved separate PRs.

@pellared pellared requested review from lmolkova and trask January 27, 2026 20:05
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

@lmolkova lmolkova added this pull request to the merge queue Jan 28, 2026
Merged via the queue into open-telemetry:main with commit 75cc19f Jan 28, 2026
17 checks passed
@github-project-automation github-project-automation bot moved this from In progress to Done in Logs SIG Jan 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: Done
Archived in project

Development

Successfully merging this pull request may close these issues.

5 participants