Skip to content

Exception attributes

spanerr.Record and spanerr.RecordFailure write one set of attributes, built from a go/errors error. The span event and the log-based event carry the same set.

The attributes

Attribute Value Left off when
exception.type errors.KindOf(err) it is ""
exception.message err.Error(), unredacted never
exception.stacktrace errors.OriginStack(err).String(): where the error was created, in Go's panic format the error carries no stack
phpboyscout.error.hints errors.Hints(err), as a string slice there are none
phpboyscout.error.details errors.Details(err), as a string slice there are none
the caller's keys errors.Attrs(err) see below

exception.message is not redacted, and neither are hints, details or attributes. Redact once, in the collector or an SDK processor.

What exception.type holds

KindOf skips go/errors' annotation wrappers, so attaching attributes or a hint does not change the type. Measured against go/errors v0.3.0:

Built with exception.type
errors.New("boom") errors.basic
errors.Wrap(errors.New(...), ...) errors.basic
errors.Newf(...) left off
errors.Wrap(io.EOF, ...) left off
errors.Wrap(ErrGone, ...), where ErrGone comes from NewSentinel("probe.gone", ...) probe.gone
fmt.Errorf("x: %w", io.EOF) left off, and so is exception.stacktrace

How the caller's attributes are converted

slog value Recorded as
string, int64, bool, float64 the same OTel type
a group, slog.Group("req", slog.String("id", "x")) dotted keys, req.id
a slog.LogValuer its resolved value
uint64, duration, time, or anything else its string form

Three rules apply on top:

  • A key spanerr sets wins. A caller's attribute keyed exception.type, exception.message, exception.stacktrace, phpboyscout.error.hints or phpboyscout.error.details is dropped, even when spanerr leaves that key off.
  • Duplicate keys pass through in order. errors.Attrs keeps them, outermost layer first, and spanerr does not merge them. On a span event they all arrive. On a log record the log SDK keeps only the last value for a key, unless the logger provider was built with sdklog.WithAllowKeyDuplication().
  • An attribute with an empty key is dropped, except a group, whose members are recorded without a prefix.

Which signals get the attributes

OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN decides. It is read once, at the first call.

Value Span event Log record
unset, or any other value written when the span is recording not written
logs not written written when the global logger is enabled for it
logs/dup written when the span is recording written when the global logger is enabled for it

The function checks both conditions before reading the error. When neither signal will be written, the error is never read.

Fail writes neither signal. It sets the span's status to Error with err.Error() as the description, and does nothing when err is nil or the span is not recording.

The log record

Field Value
event name WithEventName, else ContextWithEventName, else exception
severity from the span's kind, below
timestamp when the call was made
trace and span IDs from the span in ctx, sampled or not
body empty
instrumentation scope gitlab.com/phpboyscout/go/observability/spanerr, schema URL https://opentelemetry.io/schemas/1.26.0
Span kind Severity
client, producer WARN
server, consumer ERROR
internal, or a kind that cannot be read WARN from Record, ERROR from RecordFailure

A span that is not sampled hides its kind, so its record always takes the last row.

Logger.Enabled is asked with the same event name and severity before anything is built, so an SDK processor can filter on either.

Source

Spec 0002, render an error onto a span records the decision behind each row.