uotel

func ClassifyCtxErr ¶ added in v0.10.0

func ClassifyCtxErr(err error) string

ClassifyCtxErr maps a context error to a low-cardinality enum label suitable for a span attribute: "nil", "canceled", "deadline_exceeded", or "other" for anything that doesn't unwrap to one of the standard context sentinels.

func EndSpanWithError ¶ added in v0.8.22

func EndSpanWithError(span trace.Span, err error)

EndSpanWithError ends a span and records the error if it is non-nil and not an expected error. Expected errors (context cancellation, deadline exceeded) are recorded with an Unset status to avoid polluting error dashboards.

func InitOtel ¶

func InitOtel(ctx context.Context, opts ...Option) (context.Context, func(context.Context) error, error)

InitOtel initializes OpenTelemetry with the given configuration. It returns a function that can be called to shutdown OpenTelemetry.

func IsExpectedError ¶ added in v0.8.22

func IsExpectedError(err error) bool

IsExpectedError returns true for errors that are expected during normal operation and should not be recorded as span errors.

For an errors.Join result, true is returned only when EVERY child is itself expected. Otherwise a real error joined with a context cancel would be silently downgraded to Unset span status and dropped from error dashboards.

func ParentCtxErrLabel ¶ added in v0.10.0

func ParentCtxErrLabel(ctx context.Context) (string, bool)

ParentCtxErrLabel returns the label set by WithParentCtxErrLabel, or the empty string and ok=false if no label was propagated.

func StartWithLink ¶ added in v0.9.14

func StartWithLink(
	ctx context.Context,
	tracer trace.Tracer,
	name string,
	opts ...trace.SpanStartOption,
) (context.Context, trace.Span)

StartWithLink starts a new root span linked to the current span in ctx.

When ctx already carries a valid span context, the new span is started with trace.WithNewRoot() and a trace.Link back to that span. This breaks the causal chain into a new trace while preserving navigability via the link.

Prefer plain tracer.Start for ordinary nested spans. Reach for this only when an outer span would otherwise accumulate hundreds or thousands of children — e.g. a long-running loop that processes each item via a chain of helper spans. Mirrors ctxotel.StartWithLink in the ConductorOne platform repo.

Safe to call with the no-op tracer or with a ctx that has no span: the link is omitted and behavior matches tracer.Start. The returned ctx carries the new span, so descendants attach to the new root.

func WithParentCtxErrLabel ¶ added in v0.10.0

func WithParentCtxErrLabel(ctx context.Context, label string) context.Context

WithParentCtxErrLabel returns a new context that carries label as the parent's classified ctx-error. ParentCtxErrLabel reads it back. Use this immediately after context.WithoutCancel so a downstream finalize span can record what the original caller saw.