observability

type Config ¶

type Config struct {
	Profiling profilingcfg.Config `envPrefix:"PROFILING_" json:"profiling"`
	Logging   loggingcfg.Config   `envPrefix:"LOGGING_"   json:"logging"`
	Metrics   metricscfg.Config   `envPrefix:"METRICS_"   json:"metrics"`
	Tracing   tracingcfg.Config   `envPrefix:"TRACING_"   json:"tracing"`
	// contains filtered or unexported fields
}

Config contains settings about how we report our metrics.

func (cfg *Config) ProvidePillars(ctx context.Context) (*Pillars, error)

func (cfg *Config) ValidateWithContext(ctx context.Context) error

type Matcher ¶

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

Matcher describes a predicate over a single Observation, used by the ordered and per-operation assertion helpers.

func ObservedKey(key string) Matcher

func ObservedKeyFunc(key string, pred func(value any) bool) Matcher

func ObservedKeyValue(key string, value any) Matcher

func ObservedValue(value any) Matcher

func (m Matcher) OnLog() Matcher

func (m Matcher) OnSpan() Matcher

type Observation ¶

type Observation struct {
	Value  any
	Key    string
	Seq    int
	Pillar Pillar
}

Observation is a single recorded attachment, in the order it occurred. Seq is a monotonic counter shared across every Operation of the owning observer, so the relative order of observations from different operations is recoverable.

type Observer ¶

type Observer interface {
	Begin(ctx context.Context) (context.Context, Operation)
	BeginCustom(ctx context.Context, name string, opts ...trace.SpanStartOption) (context.Context, Operation)
	Logger() logging.Logger
	Tracer() tracing.Tracer
}

Observer bundles a named logger and tracer for a single component, so that a component holds one observability field instead of a logger/tracer pair. Each traced operation begins via Begin, which returns an Operation that records selected values to the active span and a span-linked logger simultaneously.

It is an interface so that unit tests can substitute a recording implementation (see NewRecordingObserver) and assert which fields a unit observed.

func NewObserver(name string, logger logging.Logger, tracerProvider tracing.TracerProvider) Observer

func NewObserverForTest(name string) Observer

func NewObserverWithTracer(name string, logger logging.Logger, tracer tracing.Tracer) Observer

type Operation ¶

type Operation interface {
	Set(key string, value any) Operation
	SetValues(values map[string]any) Operation
	SpanOnly(key string, value any) Operation
	LogOnly(key string, value any) Operation
	Logger() logging.Logger
	Span() tracing.Span
	Error(err error, descriptionFmt string, descriptionArgs ...any) error
	Acknowledge(err error, descriptionFmt string, descriptionArgs ...any)
	GRPCStatus(err error, code codes.Code, descriptionFmt string, descriptionArgs ...any) error
	End()
}

Operation is the per-call observability bag returned by Observer.Begin. A value recorded via Set lands on both the active span and the running logger, so a value selected once is available to either pillar later. SpanOnly and LogOnly are escape hatches for the occasions where a value belongs to just one.

It is an interface so that a recording Observer can hand back an Operation a test can read values off of (see RecordingOperation).

type Pillar ¶

type Pillar uint8

Pillar identifies where an observation landed.

const (
	// PillarBoth marks a value recorded via Set (span and logger).
	PillarBoth Pillar = iota
	// PillarSpan marks a value recorded via SpanOnly.
	PillarSpan
	// PillarLog marks a value recorded via LogOnly.
	PillarLog
)

type Pillars ¶

type Pillars struct {
	Logger          logging.Logger
	TracerProvider  tracing.TracerProvider
	MetricsProvider metrics.Provider
	Profiler        profiling.Provider
}

Pillars holds the four observability pillars: logging, tracing, metrics, and profiling.

type RecordingObserver ¶

type RecordingObserver struct {
	Operations []*RecordingOperation
	// contains filtered or unexported fields
}

RecordingObserver is an Observer implementation for unit tests. It captures, in order, every value attached to the Operations it hands out, so a test can assert which fields a unit observed, in what order, and on which pillar. It performs no real logging or tracing.

func NewRecordingObserver() *RecordingObserver

func (o *RecordingObserver) Begin(ctx context.Context) (context.Context, Operation)

func (o *RecordingObserver) BeginCustom(ctx context.Context, _ string, _ ...trace.SpanStartOption) (context.Context, Operation)

func (o *RecordingObserver) Logger() logging.Logger

func (o *RecordingObserver) ObservedInOrder(t TestingT, matchers ...Matcher)

func (o *RecordingObserver) ObservedOperationWithData(t TestingT, data map[string]any) *RecordingOperation

func (o *RecordingObserver) ObservedOperationWithKeys(t TestingT, keys ...string) *RecordingOperation

func (o *RecordingObserver) ObservedOperationWithValues(t TestingT, values ...any) *RecordingOperation

func (o *RecordingObserver) Stream() []Observation

func (o *RecordingObserver) Tracer() tracing.Tracer

type RecordingOperation ¶

type RecordingOperation struct {
	Observations []Observation
	Values       map[string]any
	SpanValues   map[string]any
	LogValues    map[string]any
	// Errors holds every error passed to Error, Acknowledge, or GRPCStatus.
	Errors []error
	// Ended reports whether End was called.
	Ended bool
	// contains filtered or unexported fields
}

RecordingOperation is the Operation handed out by RecordingObserver. Its exported maps record which keys reached which pillar (Values = Set, SpanValues = Set + SpanOnly, LogValues = Set + LogOnly), and Observations records the same attachments in order for precise, order-sensitive assertions.

func (op *RecordingOperation) Acknowledge(err error, _ string, _ ...any)

func (op *RecordingOperation) End()

func (op *RecordingOperation) Error(err error, descriptionFmt string, descriptionArgs ...any) error

func (op *RecordingOperation) GRPCStatus(err error, code codes.Code, descriptionFmt string, descriptionArgs ...any) error

func (op *RecordingOperation) LogOnly(key string, value any) Operation

func (op *RecordingOperation) Logger() logging.Logger

func (op *RecordingOperation) Observed(t TestingT, matchers ...Matcher)

func (op *RecordingOperation) ObservedInOrder(t TestingT, matchers ...Matcher)

func (op *RecordingOperation) Set(key string, value any) Operation

func (op *RecordingOperation) SetValues(values map[string]any) Operation

func (op *RecordingOperation) Span() tracing.Span

func (op *RecordingOperation) SpanOnly(key string, value any) Operation

type TestingT ¶

type TestingT interface {
	Helper()
	Fatalf(format string, args ...any)
}

TestingT is the minimal subset of *testing.T the assertion helpers need. It lets RecordingObserver offer ergonomic assertions without importing the testing package into production builds; *testing.T satisfies it structurally.