Add `Span.SetErrorStatus` method

[pellared]

What are you trying to achieve?

During the Logs SIG meeting on 2026-03-10, we discussed whether the tracing API should offer a more ergonomic way to record an operation's final error at the point where the span ends.

One possible direction would be to add an optional error/exception parameter, or a language-appropriate equivalent, to Span.End.

The goal is to make it easier for instrumentation to follow the error recording semantic conventions for spans when the final outcome of the operation is only known immediately before the span is finished.

Today, instrumentation often needs multiple explicit calls to:

• set error.type
• set span status
• call End

This is repetitive, easy to miss, and can lead to inconsistent adoption across languages and instrumentation libraries.

Additional context

This pattern is common in Go instrumentation. For example, OpenTelemetry Go Contrib has code like this:

ctx, span := tracer.Start(ctx, "my-span")
// ...
if err != nil {
	span.SetAttributes(otelsemconv.ErrorType(err))
	span.SetStatus(codes.Error, err.Error())
}
span.End()

With an error-aware End, this could look like:

ctx, span := tracer.Start(ctx, "my-span")
// ...
if err != nil {
	span.End(trace.WithError(err))
} else {
	span.End()
}

Another possible design would be a dedicated convenience method on Span, for example SetErrorStatus(err):

ctx, span := tracer.Start(ctx, "my-span")
defer span.End()
// ...
if err != nil {
	span.SetErrorStatus(err)
}

That shape may be more convenient in languages where End is typically registered at span creation time (for example, defer in Go, using in .NET, or with in Python). It would also fit the existing API style of SetStatus, SetAttributes, and similar mutating methods.

On the other hand, adding a new Span method may be a more disruptive API change in some languages than extending End with optional arguments or options. The tradeoffs may therefore depend on language ergonomics and API stability constraints.

I suspect multiple languages would benefit from a convenience API here, using whatever surface is most idiomatic for that language. This feels analogous to #4824 ("Add optional Exception parameter to Emit LogRecord"), but for tracing.

This is also related to the ongoing discussion about deprecating Span.RecordException:

• [DO NOT MERGE] [Trace] Deprecate Record Exception API in favor of using Logs API #4825
• https://opentelemetry.io/blog/2026/deprecating-span-events/

However, I do not think this should be treated as a direct replacement for Span.RecordException. Recording an exception event and marking a span's final outcome as failed are related but distinct concerns. A convenience API in this area would primarily help instrumentation apply the span error-recording conventions consistently at the end of an operation.

Questions for discussion

• Should the spec standardize one shape across languages, or only standardize the behavior and let each language choose an idiomatic API?
• Should this be implemented as SDK functionality, or can it be specified as an API-level helper/default implementation? Adding it at the API layer may reduce flexibility, but it could also allow new functionality without requiring all existing SDK span implementations to change immediately. E.g. if the SDK does not provide native support, then the spec may allow a default implementation that sets attributes and status.
• Should there an optional parameter to set error.type and maybe also status description if the value calculated by the SDK would not be ideal (like name of the exception type and exception message)?

_{Tip: React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

[dmathieu]

For Go specifically, I'm not sure this really matches the pattern.
Most of the time, we will call span.End() in a defer, and then won't be able to specify the error.

[pellared]

For Go specifically, I'm not sure this really matches the pattern. Most of the time, we will call span.End() in a defer, and then won't be able to specify the error.

Search query: https://sourcegraph.com/search?q=context:global+repo:%5Egithub%5C.com/open-telemetry/opentelemetry-go-contrib%24+lang:Go+%22span.End%22&patternType=keyword&sm=0

It is similar for .NET as activity.Dispose() is the usual pattern. Having an additional method would be more viable.

EDIT: I updated the issue description.

[abhay1999]

I'd like to work on a spec PR for this.

Based on the discussion, it seems `SetErrorStatus(err)` as a dedicated method (Option 2) is the preferred direction over extending `Span.End()`, especially given Go's `defer span.End()` pattern where the error isn't known at deferral time.

A few questions before I draft:

1. Scope of the spec PR — Should `SetErrorStatus` be defined as a MUST or SHOULD on the Span interface? Given that it's a convenience wrapper over `SetStatus(Error, ...)` + `SetAttributes(error.type)`, I'd assume SHOULD, similar to how `RecordException` is a SHOULD for languages that use exceptions.

2. Attribute behavior — Should the method automatically set `error.type` from the error object, or only set the span status to `Error`? The issue mentions both, but I want to confirm the minimum required behavior.

3. Relation to `RecordException` — Should the spec note the distinction explicitly (i.e., `SetErrorStatus` sets the final status, while `RecordException` records an event)? This seems important for implementors.

Happy to start with the spec markdown in `specification/trace/api.md` and follow up with a reference implementation in `opentelemetry-go` if that helps validate the design.

[flc1125]

To simplify error handling, I usually handle it like this:

func doSomething(ctx context.Context, tracer trace.Tracer) (err error) {
	ctx, span := tracer.Start(ctx, "doSomething")
	defer span.End()

	defer func() {
		if err != nil {
			span.RecordError(err)
			span.SetStatus(codes.Error, err.Error())
		}
	}()

	// do something that might fail

	return nil
}

So, I’m wondering whether, in span.End(), providing an option for End could simplify this kind of handling.

[dmathieu]

I'd like to work on a spec PR for this.

It's way too early to start working on a PR. we need actual human agreement at this stage.

I think a span.SetErrorStatus() that both sets the status, and reports the error would make sense.

[abhay1999]

Makes sense, holding off on a PR for now — thanks for the heads up @dmathieu!

The dual behavior idea (set status + record the error together) really clicks for me. Looking at @flc1125's snippet, that's exactly the pattern people end up writing over and over — two calls wrapped in a deferred closure just to handle one error. It's the kind of thing that looks fine until someone forgets one of the two calls and you end up with a span that has an error event but no error status, or vice versa.

So just to make sure I'm on the same page: when you say it "reports the error", do you mean it should also call RecordException internally, or just set the status + description? That feels like the key design question before anything else.

Also curious about the process here — is agreement in this issue thread enough to move toward a spec PR, or does something like this need a formal OTEP first? And are there other language SIGs (Java, Python, .NET) whose buy-in you'd want before this moves forward?

Happy to keep the discussion going here until there's a clear direction.

[pellared]

So just to make sure I'm on the same page: when you say it "reports the error", do you mean it should also call RecordException internally, or just set the status + description? That feels like the key design question before anything else.

I believe this is already clarified in the issue description. Most of the questions you raised are addressed there.

The only part that still seems open (at least to me) is whether we should provide a default implementation in cases where the SDK does not yet support this method. Introducing one could be a good way to keep things backward-compatible while rolling out the new API.

Also curious about the process here

This would need to go through the standard triaging process: https://github.com/open-telemetry/opentelemetry-specification/blob/main/CONTRIBUTING.md#issue-triaging

You can start preparing prototype PRs in a few languages. Those will be required as part of proposing the change: https://github.com/open-telemetry/opentelemetry-specification/blob/main/CONTRIBUTING.md#proposing-a-change

[abhay1999]

That makes sense, thanks for clarifying.

I reread the issue description and I see what you mean now. I was collapsing two separate concerns together a bit too much there. The default implementation question sounds like the most interesting open part to me too, especially if it helps make rollout smoother without forcing every SDK to grow support all at once.

And thanks for pointing me to the process docs as well. Prototype PRs across a few languages sounds reasonable once the shape is clearer here.