Skip to content

Update recording errors doc - document when to use error, exception (or both) attributes#2296

Closed
lmolkova wants to merge 6 commits intoopen-telemetry:mainfrom
lmolkova:errors-message-and-guidance-for-logs
Closed

Update recording errors doc - document when to use error, exception (or both) attributes#2296
lmolkova wants to merge 6 commits intoopen-telemetry:mainfrom
lmolkova:errors-message-and-guidance-for-logs

Conversation

@lmolkova
Copy link
Copy Markdown
Member

Fixes #2001

Updates errors guidance to cover:

  • errors vs exceptions and when to use which set of attributes
  • reporting errors on logs/events
  • reporting error.message attribute

Comment thread docs/general/recording-errors.md Outdated
Comment thread docs/general/recording-errors.md Outdated
@lmolkova lmolkova force-pushed the errors-message-and-guidance-for-logs branch from 2ec5940 to 1dc9015 Compare May 23, 2025 17:48
Comment thread docs/general/recording-errors.md Outdated
Comment thread docs/general/recording-errors.md Outdated
Liudmila Molkova and others added 2 commits May 27, 2025 08:27
@lmolkova
Copy link
Copy Markdown
Member Author

lmolkova commented Jun 8, 2025

@smaddock could you please leave specific suggestions on the content modified by this PR?

WRT

Deprecate the existing exception domain and its attributes

There is no active discussion on this - I'd suggest to start with an issue in the https://github.com/open-telemetry/opentelemetry-specification. You also probably want to read open-telemetry/opentelemetry-specification#4333

- Semantic conventions intended for cross-language applicability SHOULD use
`error.*` attributes.

- `exception` attributes SHOULD be documented for conventions that target
Copy link
Copy Markdown
Member Author

@lmolkova lmolkova Jun 9, 2025

Choose a reason for hiding this comment

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

this maybe a breaking(?) change for go/rust/no-exception languages

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

So for RUST at least - I'd tie the notion of "exception" to the presence of a backtrace on the error type.

Specifically, we want:

  • In Rust, if you are signalling any type T which implements std::error::Error with a backtrace and are logging it, you fill out exception.stacktrace with the Backtrace from Rust.
  • Following this guidance for accessing members by type on Error with a convention of attaching Backtrace as a field in Error.
  • Ensuring this guidance works with anyhow crate.

If I read this guidance correctly, this means Rust would do the following:

  • Always write error.type (the rust error type)
  • Always write error.message (using description of the rust error)
  • Optionally write exception.stacktrace (by accessing Backtrace field on Error when available.
  • Optional write exception.type to match error.type if a Backtrace exists?

Can you confirm?

Also would be good for @open-telemetry/rust-maintainers to confirm my assumptions on error handling here.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

@trask trask added this to Logs SIG Jun 24, 2025
@trask trask moved this to In progress in Logs SIG Jun 24, 2025
@github-actions
Copy link
Copy Markdown

This PR was marked stale due to lack of activity. It will be closed in 7 days.

@github-actions github-actions Bot added the Stale label Jun 25, 2025
@lmolkova lmolkova requested a review from Copilot July 1, 2025 05:44
Copy link
Copy Markdown
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 enhances the error guidance by clarifying when to use error versus exception attributes, adds logging/event recommendations, and updates examples to ensure proper error reporting.

  • Defines “Error vs exception” and when both attribute sets apply
  • Adds “Recording errors on logs and events” section
  • Updates example snippets and cross-links to the general error guidance

Reviewed Changes

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

File Description
model/error/registry.yaml Added link to the general recording-errors documentation
docs/registry/attributes/error.md Linked to the new recording-errors guide
docs/general/recording-errors.md Introduced Error vs exception section, log/event guidance, warnings, and updated examples
.chloggen/2296.yaml Updated changelog metadata
Comments suppressed due to low confidence (3)

docs/general/recording-errors.md:57

  • Consider capitalizing the first word of this bullet to match the style of other list items (e.g., change “when” to “When”).
- when the error and exception details are identical, and both sets

docs/general/recording-errors.md:170

  • The blank > line after the warning header may break the admonition rendering. Removing this blank line will ensure the warning block displays correctly.
>

docs/general/recording-errors.md:210

  • Align the finally brace indentation with the catch block for consistent formatting (e.g., match the indentation level of the closing } of the catch).
  } finally {

@github-actions github-actions Bot removed the Stale label Jul 2, 2025
@github-actions
Copy link
Copy Markdown

This PR was marked stale due to lack of activity. It will be closed in 7 days.

@github-actions github-actions Bot added the Stale label Jul 17, 2025
@jsuereth
Copy link
Copy Markdown
Contributor

@lmolkova Is this PR still active?

Comment on lines -55 to +120
It's NOT RECOMMENDED to duplicate status code or `error.type` in span status description.
It's NOT RECOMMENDED to duplicate status code, `error.type`, `error.message`,
or `exception.message` in the span status description.
Copy link
Copy Markdown

Choose a reason for hiding this comment

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

The note on the error.message attribute says it is NOT RECOMMENDED for spans. This text about duplicating error.message in the span status description may give the false impression that the attribute is preferred.

Comment on lines +35 to +37
Exceptions and how they are recorded in telemetry are inherently
language-specific. Some languages, such as Rust or Go, do not use exceptions
at all.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I think that a panic in Go be considered as an exception.
Then a deffered span.End can handle "the exception" (recover the panic and record it).
See: https://github.com/open-telemetry/opentelemetry-go/blob/b5b6989c7a08b5e4773236fc8d9fa0e5fe9788e1/sdk/trace/span.go#L476-L493

I think it would be good to clarify it.

Comment on lines +23 to +29
In the scope of this document, the terms error and exception are defined as follows:

- *Error* refers to a general concept describing any non-success condition.
This may include a non-success status code, or an invalid response.

- *Exception* specifically refers to runtime exceptions and their
associated stack traces.
Copy link
Copy Markdown
Member

@pellared pellared Oct 16, 2025

Choose a reason for hiding this comment

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

@open-telemetry/go-maintainers,

While a personally like this distinction (and I find it correct), I am not sure if/how we are going to make it in Go in a non-breaking way given https://pkg.go.dev/go.opentelemetry.io/otel/trace#Span:

	// RecordError will record err as an exception span event for this span. An
	// additional call to SetStatus is required if the Status of the Span should
	// be set to Error, as this method does not change the Span status. If this
	// span is not being recorded or err is nil then this method does nothing.
	RecordError(err error), options ...EventOption)

Maybe deprecate this function and create a new one that would record errors according to the new semantics?

Related issues:

@lmolkova
Copy link
Copy Markdown
Member Author

lmolkova commented Dec 2, 2025

Drafting this one and blocking on open-telemetry/opentelemetry-specification#4333

@lmolkova lmolkova marked this pull request as draft December 2, 2025 18:29
@lmolkova lmolkova moved this from Untriaged to Blocked in Semantic Conventions Triage Dec 2, 2025
@lmolkova lmolkova moved this from Blocked to Draft in Semantic Conventions Triage Dec 2, 2025
@lmolkova
Copy link
Copy Markdown
Member Author

lmolkova commented Dec 9, 2025

@github-actions
Copy link
Copy Markdown

This PR has been labeled as stale due to lack of activity. It will be automatically closed if there is no further activity over the next 7 days.

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.

When to use error vs exception attributes

9 participants