spanerr

package
v0.6.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package spanerr records an error from gitlab.com/phpboyscout/go/errors on the active span: its kind, message, origin stack, hints, details and attributes. It depends on the OpenTelemetry APIs only, so a library can call it without linking the SDK or an exporter.

When OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN is "logs" or "logs/dup", the exception also goes out as a log-based event through the global logger provider, tied to the span through the context.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func ContextWithEventName

func ContextWithEventName(ctx context.Context, name string) context.Context

ContextWithEventName returns ctx carrying name as the event name for exceptions recorded under it. It names the log-based event only; the span event is always "exception".

Example
package main

import (
	"net/http"

	"gitlab.com/phpboyscout/go/observability/spanerr"
)

func main() {
	namePaymentExceptions := func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			ctx := spanerr.ContextWithEventName(r.Context(), "payments.charge.exception")
			next.ServeHTTP(w, r.WithContext(ctx))
		})
	}

	_ = namePaymentExceptions
}

func Fail

func Fail(ctx context.Context, err error)

Fail sets the status of the span in ctx to codes.Error, with err's message as its description.

func Record

func Record(ctx context.Context, err error, opts ...Option)

Record records err as an exception on the span in ctx, without changing the span's status.

func RecordFailure

func RecordFailure(ctx context.Context, err error, opts ...Option)

RecordFailure records err and fails the span.

Example
package main

import (
	"context"
	"net/http"

	"gitlab.com/phpboyscout/go/errors"

	"gitlab.com/phpboyscout/go/observability/spanerr"
)

var errCardDeclined = errors.NewSentinel("payment.card_declined", "the card was declined")

func charge(_ context.Context, orderID string) error {
	return errors.WithHint(
		errors.Wrapf(errCardDeclined, "charging order %s", orderID),
		"ask the customer for another card",
	)
}

func main() {
	mux := http.NewServeMux()

	mux.HandleFunc("POST /orders/{order}/charge", func(w http.ResponseWriter, r *http.Request) {
		ctx := r.Context()

		if err := charge(ctx, r.PathValue("order")); err != nil {
			spanerr.RecordFailure(ctx, err)
			http.Error(w, "payment failed", http.StatusPaymentRequired)

			return
		}

		w.WriteHeader(http.StatusNoContent)
	})
}

Types

type Option

type Option func(*config)

Option configures a single Record or RecordFailure call.

func WithEventName

func WithEventName(name string) Option

WithEventName sets the event name for one call, overriding the context.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL