Apply the specified status precedence in Span.set_status

[WatchTree-19]

Description

Fixes #5661.

Span.set_status now applies the precedence the specification gives, Ok > Error > Unset, in one place.

Before this the rule was split across two ad-hoc conditions, one of which only reads correctly if you know Python's and/or precedence, and nothing tested it. The SDK was mostly doing the right thing already: of the twelve transitions in the lattice, eleven were correct on main. The one that was not is #5661, where a bare Status(StatusCode.ERROR) replaced Status(StatusCode.ERROR, "...") and the description was silently lost. The status code did not change, so nothing looked wrong; only the message that carried the diagnostic value disappeared.

That is reachable without anyone doing anything odd. A library sets a specific error on a span, and later generic error handling, exception bookkeeping or an instrumentation helper sets a plain ERROR on the same span.

The decision now lives in _accepts_status, and it is the whole rule:

• Unset is never recorded. An attempt to set it is ignored, whatever is already there.
• Ok is final, so Error never displaces Ok. Once Unset and Ok are handled, any code that differs from the one recorded outranks it and is recorded.
• A status repeating the code already recorded is ignored unless it supplies a description where none was recorded, so a message already on the span is never replaced and never dropped.

There is no separate ranking helper. Because Unset is ignored and Ok is final, every remaining change of code is an upgrade, so _accepts_status only has to ask whether the code differs and, when it does not, whether a missing description is being filled in.

Type of change

• Bug fix (non-breaking change which fixes an issue)

How Has This Been Tested?

opentelemetry-sdk/tests/trace/test_trace.py passes in full: 116 passed, 35 subtests passed.

The thirteen transitions are a _PRECEDENCE_CASES table in TestSpan, each entry being the calls to make and the status code and description expected. The table is driven through self.subTest and run twice, once through Status instances and once through the StatusCode overload, so the overload is exercised on every case rather than on one.

The cases were checked to discriminate rather than merely pass:

• reverting the same-code rule to the earlier new_status.description is not None turns two subtests red
• removing _accepts_status altogether turns twelve red

ruff check and ruff format are clean and pylint scores 10.00/10 on both changed files.

The behaviour was also reproduced against released opentelemetry-sdk 1.44.0 on CPython 3.11 before anything was changed, using the snippet in #5661.

Does This PR Require a Contrib Repo Change?

• Yes. - Link to PR:
• No.

Checklist:

• Followed the style guidelines of this project
• Changelogs have been updated
• Unit tests have been added
• Documentation has been updated

On the changelog: .changelog/ names fragments after the PR number, which does not exist until this is opened, so <pr>.fixed follows as a second commit straight after.

AI assistance was used and is disclosed on the commits with an Assisted-by: trailer, per AGENTS.md.

[herin049]

We should probably update this to be more in line with what the spec expects:

Namely that Span statuses form a total order Ok > Error > Unset and any attempts to update the status that are not strictly greater than the previous status should be ignored (i.e. all future calls to set status will be ignored when the status is set to Error unless the new status is Ok, and every future call to set status will be ignored when the status is set to Ok). A call to explicitly set the status to Unset should always be ignored.

[WatchTree-19]

Thanks for laying the ordering out, I went through each point against the spec. Three of the four are in there: the total order Ok > Error > Unset, "an attempt to set value Unset SHOULD be ignored", and Ok being final. I couldn't find the fourth one, ignoring anything that isn't strictly greater. The spec says "only the value of the last call will be recorded, and implementations are free to ignore previous calls." Taken to the letter, your rule would mean Error("first") followed by Error("second") keeps "first", which is what that last call sentence rules out.

I also wrote all twelve transitions up as tests and ran them against upstream main. Eleven of them pass, and the only one that fails is the bug I first reported. So the SDK was mostly doing the right thing already. The ordering just wasn't written down anywhere: it was split across two conditions, one of which only reads right if you know Python's and/or precedence, and nothing tested it.

What I've pushed now writes the order out explicitly and puts the decision in one method. It adds the twelve tests and keeps last call wins within the same rank, along with the exception for bare status. One thing worth mentioning: the enum is UNSET=0, OK=1, ERROR=2, which isn't the spec's order, so it can't be a plain enum comparison.

The main thing I wanted to check with you: should Error to Error be ignored as you wrote it, even though that goes against the spec's last call sentence? Or should the ordering be made explicit with last call wins kept, which is what's on the branch now?

[Shriprasad-P]

Nice focused PR. Please make sure docs/changelog stay aligned if the repo requires it for this kind of change.

[WatchTree-19]

@herin049 any thoughts on the Error to Error question when you get a minute? Happy to switch it to ignoring a repeat of the same code if that is what you want, it is a small change. I only left it as last call wins because the spec says the value of the last call is the one recorded, and I did not want to diverge from that without you saying so.

@Shriprasad-P thanks. The changelog fragment was rewritten alongside the code, .changelog/5662.fixed now describes the precedence change rather than the original description fix.

[herin049]

Namely that Span statuses form a total order Ok > Error > Unset

The last sentence in the spec that states "Only the value of the last call will be recorded, and implementations are free to ignore previous calls." is a little strange and partially contradicts what is stated earlier in the paragraph. As a whole, I take this to mean that if a higher precedence status is set on a span, then previous calls can be ignored.

I would expect that it is safe to ignore calls to set the status to Error if the status already is Error.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on maintainers · refreshed 2026-09-21 17:31 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.

[WatchTree-19]

Thanks. The changelog fragment is already in the branch, .changelog/5662.fixed, which is the format this repo moved to instead of editing CHANGELOG.md directly. It covers all three behaviours the patch changes: the Ok > Error > Unset order being enforced explicitly, Unset always being ignored, and a bare Status(ERROR) no longer dropping a description that was already recorded. No user-facing docs reference the old behaviour, so nothing else needed there as far as I can see, but happy to add to it if you think somewhere else should call this out.

[WatchTree-19]

Thanks, all three are in 69b6ab6 and I have replied on each thread.

The one behaviour change is the first. A status that repeats the code already recorded is now ignored unless it supplies a description where none was recorded, so a message already on the span is never replaced and never dropped. That is your Error to Error point as well, and I am happy with it: the ordering is about codes, and once the code is unchanged the only call left carrying new information is one that adds a message. So the last call sentence still governs, it just governs the description rather than licensing a bare overwrite.

Verification: 116 passed and 35 subtests passed in opentelemetry-sdk/tests/trace/test_trace.py on CPython 3.11, ruff check and ruff format clean, pylint 10.00/10 on both changed files. The cases were checked to discriminate rather than merely pass. Reverting the same-code rule to the earlier description is not None turns two subtests red, and removing _accepts_status altogether turns twelve red.

The changelog fragment now describes the precedence behaviour as it stands, and I have rewritten the PR description to match, since it still named the old tests.

[Copilot]

Copilot review overview

🟡 Changes recommended

Same-code handling incorrectly prevents replacing an existing error description with a newer one.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Preserve descriptions on same-code ERROR updates · New
• Use “an” before “Unset” · New

What changed in this PR

Updates SDK span status handling to enforce status-code precedence and preserve error descriptions.

Changes:

• Centralizes status precedence logic.
• Adds transition tests for both accepted input forms.
• Adds a changelog entry.

File	Description
opentelemetry-sdk/​src/​opentelemetry/​sdk/​trace/​__init__.py	Implements status precedence.
opentelemetry-sdk/​tests/​trace/​test_trace.py	Tests status transitions.
.changelog/​5662.fixed	Documents the fix.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.