observability

Documentation

Overview

Package observability provides request tracing, metrics recording, and structured logging helpers for gofly services.

Package observability provides request tracing, metrics recording, structured logging and profiling endpoints for gofly services.

Index

• func Record(registry *metrics.Registry, name string, status int, duration time.Duration)
• func ShouldLog(ctx context.Context, sampler trace.Sampler, status int) bool
• func StartTrace(ctx context.Context, parent string, service string, sampler trace.Sampler) (context.Context, trace.SpanContext)
• func TraceAttrs(ctx context.Context) []any
• type Config
• type LogSamplingConfig
• type LoggerConfig
• type Observe
  • func NewObserve(cfg ObserverConfig) *Observe
  • func (o *Observe) Handler() http.Handler
  • func (o *Observe) Logger() *slog.Logger
  • func (o *Observe) Register(mux *http.ServeMux, prefix string)
  • func (o *Observe) Registry() *metrics.Registry
• type Observer
  • func New(conf Config) *Observer
  • func (o *Observer) Start(name string, attrs ...any) *Operation
• type ObserverConfig
• type Operation
  • func (op *Operation) End(ctx context.Context, status int, err error, message string, attrs ...any)
• type RotateConfig

Functions

func Record

func Record(registry *metrics.Registry, name string, status int, duration time.Duration)

func ShouldLog

func ShouldLog(ctx context.Context, sampler trace.Sampler, status int) bool

func StartTrace

func StartTrace(ctx context.Context, parent string, service string, sampler trace.Sampler) (context.Context, trace.SpanContext)

func TraceAttrs

func TraceAttrs(ctx context.Context) []any

Types

type Config

type Config struct {
	Service    string
	Registry   *metrics.Registry
	Logger     *slog.Logger
	LogSampler trace.Sampler
}

Config configures the Observer.

type LogSamplingConfig

type LogSamplingConfig struct {
	First      int
	Thereafter int
}

LogSamplingConfig drops repeated similar messages at high throughput to keep the log volume bounded. A message is identified by level+message. The first First messages of each key pass through; thereafter one message every Thereafter-th is kept, the rest are dropped.

type LoggerConfig

type LoggerConfig struct {
	Level     slog.Level
	JSON      bool
	AddSource bool
	// SetGlobal installs this logger as slog.Default() when non-nil LoggerConfig
	// is passed to NewObserve. Disabled by default to avoid surprising side
	// effects; enable explicitly when you want free-form slog calls to share the
	// same destination and format.
	SetGlobal bool
	Sampling  *LogSamplingConfig
	Output    io.Writer
	// Rotate optionally enables size-based log file rotation. When set,
	// Output is ignored and writes go through the rotating file.
	Rotate *RotateConfig
}

LoggerConfig controls how the service emits structured logs. If zero, the default is a human-readable text logger at Info level writing to stderr.

type Observe

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

Observe wires together metrics, logging, tracing, and (optionally) pprof diagnostics behind a single http.Handler. Mount it on an internal admin port or under /debug on your main server. This is the "single object" companion to the more granular Observer/Operation API defined in observability.go; pick whichever fits your wiring style.

func NewObserve

func NewObserve(cfg ObserverConfig) *Observe

NewObserve builds and returns an Observe, installing its logger as slog.Default so free-form slog calls share the same formatting.

func (*Observe) Handler

func (o *Observe) Handler() http.Handler

Handler exposes diagnostics endpoints (metrics, json, pprof when enabled) as a single http.Handler. Safe to use with http.ServeMux by prefix.

func (*Observe) Logger

func (o *Observe) Logger() *slog.Logger

Logger returns the configured structured logger.

func (*Observe) Register

func (o *Observe) Register(mux *http.ServeMux, prefix string)

Register attaches the observer's handler onto an existing mux using the given prefix (typically "/debug"). Empty prefix is treated as "/".

func (*Observe) Registry

func (o *Observe) Registry() *metrics.Registry

Registry returns the metrics registry wired to the observer.

type Observer

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

Observer records traces, metrics, and logs for operations.

func New

func New(conf Config) *Observer

New creates an Observer from Config.

func (*Observer) Start

func (o *Observer) Start(name string, attrs ...any) *Operation

type ObserverConfig

type ObserverConfig struct {
	Service    string
	Registry   *metrics.Registry
	Logger     *LoggerConfig
	Sampler    trace.Sampler
	Pprof      bool
	ExposeJSON bool
}

ObserverConfig bundles all observability knobs for a service. The zero value produces sensible defaults: Default metrics registry, text slog, no sampling, pprof exposed under the /debug/pprof/ prefix.

type Operation

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

Operation represents a single observable operation.

func (*Operation) End

func (op *Operation) End(ctx context.Context, status int, err error, message string, attrs ...any)

type RotateConfig

type RotateConfig struct {
	Filename   string
	MaxBytes   int64
	MaxBackups int
	MaxAgeDays int
	LocalTime  bool
}

RotateConfig enables size-based log rotation. One primary log file plus MaxBackups rotated copies are kept on disk, each capped at MaxBytes.