wrapper

type Attr ¶

type Attr struct {
	Key   string
	Value any
}

Attr is a key-value pair recorded on a Span. Value is any so adapters can handle type-specific conversions (OTel attribute.Key, slog fields, ...); producers should prefer string / int64 / bool for cross-adapter portability.

type AttrCarrier ¶

type AttrCarrier struct {
	Attrs []Attr
}

AttrCarrier is a mutable holder for contract-derived span attributes. It is installed into the request context by the outer HTTP Tracing middleware before routing; HTTPHandler appends to it when the request reaches the contract-bound handler; Tracing reads the slice back after next.ServeHTTP returns and late-binds the attributes onto the single request-owned span.

The carrier pattern mirrors chi's RouteContext: a pointer is stored in ctx once at the outermost layer, and nested handlers mutate its target. This is the canonical Go idiom when data must propagate "upwards" from a nested handler to an outer middleware span, since context.WithValue only adds new values to derived children.

Rationale for putting the type + helpers in kernel/wrapper (not kernel/ctxkeys):

• the typed Attr slice is wrapper.Attr; keeping the carrier next to its payload type avoids cycles in the opposite direction.
• kernel/wrapper already depends on kernel/ctxkeys for ContractID, so the ctxkeys.ContractAttrs key can be referenced here directly.

ref: go-chi/chi/v5 middleware/middleware.go — RouteContext's mutable routeContext struct in ctx, propagated up via chi-internal pointer.

func AttrCarrierFrom(ctx context.Context) (*AttrCarrier, bool)

type ConsumerFunc ¶

type ConsumerFunc = outbox.EntryHandler

ConsumerFunc mirrors outbox.EntryHandler so Cells can wrap their existing handlers without changing signatures. It is re-exported here so wrapper callers do not need to import kernel/outbox for the type.

func WrapConsumer(tr Tracer, spec contractspec.ContractSpec, fn ConsumerFunc) (ConsumerFunc, error)

type Disposition ¶

type Disposition = outbox.Disposition

Disposition is an alias for outbox.Disposition.

type Entry ¶

type Entry = outbox.Entry

Entry is an alias for outbox.Entry. Use wrapper.Entry in handler signatures.

type HandleResult ¶

type HandleResult = outbox.HandleResult

HandleResult is an alias for outbox.HandleResult.

type NoopTracer ¶

type NoopTracer struct{}

NoopTracer is a zero-allocation Tracer. Used by WrapConsumer as the fallback when no runtime tracer is wired (nil Tracer argument), and by tests that exercise the wrapper path without an adapter dependency.

HTTPHandler no longer creates spans (the outer HTTP Tracing middleware owns the single request span), so it does not reference Tracer at all — NoopTracer is only used on the consumer side (WrapConsumer) where the event router is the span owner and bootstrap is the tracer injector.

func (NoopTracer) Start(ctx context.Context, _ string, _ ...Attr) (context.Context, Span)

type Span ¶

type Span interface {
	// SetAttributes records key-value pairs on the span.
	SetAttributes(attrs ...Attr)
	// RecordError attaches an error event to the span. Recording an error
	// does not by itself mark the span as failed — callers should also call
	// SetStatus(StatusError, "...") when the error is terminal.
	RecordError(err error)
	// SetStatus records the final success/failure status for the span. The
	// last SetStatus call wins. Description is free-form; adapters MAY
	// truncate long values.
	SetStatus(code StatusCode, description string)
	// End finalizes the span. Calls after End are no-ops; implementations
	// SHOULD ignore post-End mutations silently.
	End()
}

Span represents a single unit of work in a trace. Implementations MUST be safe for concurrent use — middleware and handlers running on the same request may emit attributes from multiple goroutines (ResponseWriter observers, error recorders, etc.).

type SpanRenamer ¶

type SpanRenamer interface {
	SetName(name string)
}

SpanRenamer is an optional interface that a Span implementation MAY support when the final span name is only known after the handler / routing completes (e.g. chi matches the path template post-ServeHTTP). Helpers that want to stay compatible with Span implementations lacking rename support should use SetSpanName instead of a direct type assertion.

NoopTracer's span implements SetName as a silent no-op, so callers can invoke SetSpanName unconditionally regardless of whether a real tracer is wired — there is no "rename unsupported" branch to worry about when tracing is disabled.

ref: riandyrn/otelchi middleware.go — chi routes are known after ServeHTTP so span.name is adjusted in two phases.

type StatusCode ¶

type StatusCode int

StatusCode is the span-level success / failure marker. Adapters translate these ordinals into backend-specific status codes (OTel `codes.Ok`/`codes.Error`, Zipkin error tags, etc.).

const (
	// StatusOK indicates the span completed successfully. It is the zero value
	// so Span implementations default to OK unless SetStatus is called.
	StatusOK StatusCode = 0
	// StatusError marks the span as failed; adapters SHOULD surface this as
	// an error-level classification in their backend.
	StatusError StatusCode = 1
)

type Tracer ¶

type Tracer interface {
	Start(ctx context.Context, spanName string, attrs ...Attr) (context.Context, Span)
}

Tracer creates spans. The returned context carries the span so downstream code may read the active trace identity via TraceIDFromContext / SpanIDFromContext.

Implementations that continue a trace present on the input context (e.g. an OTel SDK) SHOULD do so; the NoopTracer accepts any context unchanged.