observability

Documentation

Overview

Package observability provides instance-owned contracts and adapters for Spice's dependency-free lifecycle, HTTP, and generated method observations.

Index

• Variables
• func NewSlogLifecycleObserver(logger *slog.Logger) (lifecycle.Observer, error)
• func Observe(ctx context.Context, definition MethodDefinition, observers []MethodObserver, ...) (resultErr error)
• type LoggingObservers
  • func NewLoggingObservers(logger *logging.Logger) (*LoggingObservers, error)
• type MethodDefinition
• type MethodObserver
• type MethodResult
• type MethodWork
• type SlogHTTPObserver
  • func NewSlogHTTPObserver(logger *slog.Logger) (*SlogHTTPObserver, error)
  • func (observer *SlogHTTPObserver) BeginHTTP(ctx context.Context, route web.RouteMetadata) (context.Context, func(web.HTTPResult))

Variables

var ErrMethodPanicked = errors.New("observed method panicked")

ErrMethodPanicked identifies a method observation completed by a panic. Observe reports it and then re-panics with the original value.

Functions

func NewSlogLifecycleObserver

func NewSlogLifecycleObserver(logger *slog.Logger) (lifecycle.Observer, error)

NewSlogLifecycleObserver constructs a structured lifecycle observer. Begin records use debug level; successful completion uses info and failures use error. Component and module values come from compiler-generated metadata.

func Observe

func Observe(
	ctx context.Context,
	definition MethodDefinition,
	observers []MethodObserver,
	work MethodWork,
) (resultErr error)

Observe executes work once and reports completion to instance-owned observers. Observer contexts are composed in declaration order and completion callbacks run in reverse order. Panics are observed and re-raised.

Types

type LoggingObservers

type LoggingObservers struct {
	Lifecycle     lifecycle.Observer
	HTTP          web.HTTPObserver
	Method        MethodObserver
	Authorization security.Observer
	Schedule      schedule.Observer
	Async         async.Observer
	Retry         retry.Observer
	Cache         cache.Observer
	Event         spiceevent.Observer
	Transaction   data.Observer
	Batch         batch.Observer
	Outbox        outbox.Observer
	Migration     migration.Observer
	Mail          mailtest.Observer
}

LoggingObservers contains one safe adapter for every public Spice observation seam. Generated code selects only the fields it needs.

func NewLoggingObservers

func NewLoggingObservers(logger *logging.Logger) (*LoggingObservers, error)

NewLoggingObservers constructs instance-owned, payload-free adapters.

type MethodDefinition

type MethodDefinition struct {
	ID      string
	Module  string
	Service string
	Method  string
}

MethodDefinition is compiler-owned metadata for one observed service method.

type MethodObserver

type MethodObserver interface {
	BeginMethod(context.Context, MethodDefinition) (context.Context, func(MethodResult))
}

MethodObserver begins one method observation on the calling goroutine. It may return a derived context and an optional completion callback.

type MethodResult

type MethodResult struct {
	Definition MethodDefinition
	Duration   time.Duration
	Err        error
	Panicked   bool
}

MethodResult describes one completed observed method invocation.

type MethodWork

type MethodWork func(context.Context) error

MethodWork is generated service-method logic executed within observation.

type SlogHTTPObserver

type SlogHTTPObserver struct {
	// contains filtered or unexported fields
}

SlogHTTPObserver writes one bounded, route-template-based completion record for each generated HTTP request. It never records raw URLs, headers, bodies, query values, or client-provided path values.

func NewSlogHTTPObserver

func NewSlogHTTPObserver(logger *slog.Logger) (*SlogHTTPObserver, error)

NewSlogHTTPObserver constructs an instance-owned structured HTTP observer.

func (*SlogHTTPObserver) BeginHTTP

func (observer *SlogHTTPObserver) BeginHTTP(
	ctx context.Context,
	route web.RouteMetadata,
) (context.Context, func(web.HTTPResult))

BeginHTTP implements web.HTTPObserver.