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.hintsorphpboyscout.error.detailsis dropped, even when spanerr leaves that key off. - Duplicate keys pass through in order.
errors.Attrskeeps 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 withsdklog.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.