Documentation
¶
Overview ¶
Package observability provides Prometheus metrics, structured logging via slog, and OpenTelemetry tracing for the Helix framework.
Index ¶
- Variables
- func ConfigureLogging(loader config.Loader, opts ...LoggingOption) (*slog.Logger, error)
- func ConfigureTracing(loader config.Loader, opts ...TracingOption) (trace.TracerProvider, func(context.Context) error, error)
- func Logger(namespace string) *slog.Logger
- func NewHTTPMetricsObserver(registry *prometheus.Registry) (web.RouteObserver, error)
- func NewRegistry() (*prometheus.Registry, error)
- func RegisterActuatorRoutes(server web.HTTPServer, checker HealthChecker, info InfoProvider) error
- func RegisterMetricsRoute(server web.HTTPServer, registry *prometheus.Registry, ...) error
- func Registry() *prometheus.Registry
- type ComponentHealth
- type CompositeHealthChecker
- type HealthChecker
- type HealthIndicator
- type HealthResponse
- type InfoOption
- type InfoProvider
- type InfoResponse
- type LoggingConfig
- type LoggingOption
- type MetricsRouteOption
- type Status
- type TracingConfig
- type TracingOption
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidActuator = errors.New("observability: invalid actuator")
ErrInvalidActuator is returned when actuator routes cannot be registered.
var ErrInvalidHealthIndicator = errors.New("observability: invalid health indicator")
ErrInvalidHealthIndicator is returned when a health indicator cannot be used.
var ErrInvalidLogging = errors.New("observability: invalid logging")
ErrInvalidLogging is returned when logging configuration is invalid.
var ErrInvalidMetrics = errors.New("observability: invalid metrics")
ErrInvalidMetrics is returned when metrics routes or observers cannot be configured.
var ErrInvalidTracing = errors.New("observability: invalid tracing")
ErrInvalidTracing is returned when tracing configuration is invalid.
Functions ¶
func ConfigureLogging ¶
ConfigureLogging builds a structured JSON logger from loader (or opts) and installs it as slog.Default(). Returns the configured logger or an error. Note: this function calls slog.SetDefault; it is not safe to call concurrently.
func ConfigureTracing ¶
func ConfigureTracing(loader config.Loader, opts ...TracingOption) (trace.TracerProvider, func(context.Context) error, error)
ConfigureTracing initialises OpenTelemetry tracing from loader and opts.
When tracing is disabled (default), ConfigureTracing returns (nil, nil, nil) and does NOT call otel.SetTracerProvider. The caller must check for a nil provider before passing it to web.WithTracerProvider.
When tracing is enabled, ConfigureTracing calls otel.SetTracerProvider and otel.SetTextMapPropagator as a side effect. The returned shutdown function must be called (e.g. via defer) to flush and close the exporter.
loader may be nil when WithTracingConfig is provided (test usage).
func Logger ¶
Logger returns a *slog.Logger pre-annotated with the given namespace. It reads from the current slog.Default() so it always reflects the Helix configuration.
func NewHTTPMetricsObserver ¶
func NewHTTPMetricsObserver(registry *prometheus.Registry) (web.RouteObserver, error)
NewHTTPMetricsObserver creates a RouteObserver that records HTTP metrics into registry. The two collectors are registered immediately; an error is returned if registration fails (e.g., duplicate registration).
func NewRegistry ¶
func NewRegistry() (*prometheus.Registry, error)
NewRegistry creates a fresh, isolated Prometheus registry. Prefer this in tests to avoid cross-test metric collisions.
func RegisterActuatorRoutes ¶
func RegisterActuatorRoutes(server web.HTTPServer, checker HealthChecker, info InfoProvider) error
RegisterActuatorRoutes registers the health and info actuator endpoints.
func RegisterMetricsRoute ¶
func RegisterMetricsRoute(server web.HTTPServer, registry *prometheus.Registry, opts ...MetricsRouteOption) error
RegisterMetricsRoute registers GET /actuator/metrics on server using the provided Prometheus registry. The response uses the standard Prometheus text exposition format (text/plain).
An optional guard can be supplied via WithMetricsGuard; by default the endpoint is public.
func Registry ¶
func Registry() *prometheus.Registry
Registry returns the singleton Helix Prometheus registry. Use NewRegistry() in tests to obtain an isolated registry.
Types ¶
type ComponentHealth ¶
type ComponentHealth struct {
Status Status `json:"status"`
Details map[string]any `json:"details,omitempty"`
Error string `json:"error,omitempty"`
}
ComponentHealth describes the health of one named component.
type CompositeHealthChecker ¶
type CompositeHealthChecker struct {
// contains filtered or unexported fields
}
CompositeHealthChecker combines several indicators into one health response.
func HealthCheckerFromContainer ¶
func HealthCheckerFromContainer(container *core.Container) (*CompositeHealthChecker, error)
HealthCheckerFromContainer builds a checker from registered HealthIndicator components.
func NewCompositeHealthChecker ¶
func NewCompositeHealthChecker(indicators ...HealthIndicator) (*CompositeHealthChecker, error)
NewCompositeHealthChecker creates a deterministic health checker.
func (*CompositeHealthChecker) Check ¶
func (c *CompositeHealthChecker) Check(ctx context.Context) HealthResponse
Check returns the aggregate health response.
type HealthChecker ¶
type HealthChecker interface {
Check(context.Context) HealthResponse
}
HealthChecker evaluates the application health.
type HealthIndicator ¶
type HealthIndicator interface {
Name() string
Health(context.Context) ComponentHealth
}
HealthIndicator is implemented by components that contribute to health.
type HealthResponse ¶
type HealthResponse struct {
Status Status `json:"status"`
Components map[string]ComponentHealth `json:"components,omitempty"`
}
HealthResponse is the JSON response returned by /actuator/health.
type InfoOption ¶
type InfoOption func(*defaultInfoProvider)
InfoOption configures the default info provider.
func WithBuildInfo ¶
func WithBuildInfo(build map[string]string) InfoOption
WithBuildInfo configures build metadata reported by /actuator/info.
func WithVersion ¶
func WithVersion(version string) InfoOption
WithVersion configures the version reported by /actuator/info.
type InfoProvider ¶
type InfoProvider interface {
Info(context.Context) InfoResponse
}
InfoProvider supplies application metadata for /actuator/info.
func NewInfoProvider ¶
func NewInfoProvider(loader config.Loader, opts ...InfoOption) InfoProvider
NewInfoProvider creates the default InfoProvider.
type InfoResponse ¶
type InfoResponse struct {
Version string `json:"version"`
Profiles []string `json:"profiles"`
Build map[string]string `json:"build"`
}
InfoResponse is the JSON response returned by /actuator/info.
type LoggingConfig ¶
type LoggingConfig struct {
// Level is the global log level: debug, info, warn, error.
Level string
// Levels maps a namespace to its specific level, e.g. {"web": "debug"}.
Levels map[string]string
}
LoggingConfig holds the logging configuration resolved from helix.logging.*.
type LoggingOption ¶
type LoggingOption func(*loggingOptions) error
LoggingOption configures ConfigureLogging.
func WithDefaultNamespace ¶
func WithDefaultNamespace(ns string) LoggingOption
WithDefaultNamespace sets the namespace injected when no explicit namespace is provided.
func WithLoggingConfig ¶
func WithLoggingConfig(cfg LoggingConfig) LoggingOption
WithLoggingConfig provides an explicit LoggingConfig, bypassing loader lookup.
func WithLoggingOutput ¶
func WithLoggingOutput(w io.Writer) LoggingOption
WithLoggingOutput redirects log output (useful in tests).
type MetricsRouteOption ¶
type MetricsRouteOption func(*metricsRouteOptions)
MetricsRouteOption configures the metrics route registration.
func WithMetricsGuard ¶
func WithMetricsGuard(guard web.Guard) MetricsRouteOption
WithMetricsGuard installs an optional guard on /actuator/metrics. By default the endpoint is public. Pass a guard to restrict access. A nil or typed-nil guard returns ErrInvalidMetrics at registration time.
type TracingConfig ¶
type TracingConfig struct {
Enabled bool
Exporter string // "stdout" | "otlp" | "jaeger"
Endpoint string // OTLP HTTP endpoint, default "localhost:4318"
ServiceName string // default "helix"
}
TracingConfig holds the configuration for OpenTelemetry tracing.
type TracingOption ¶
type TracingOption func(*tracingOptions)
TracingOption configures the tracing setup.
func WithTracingConfig ¶
func WithTracingConfig(cfg TracingConfig) TracingOption
WithTracingConfig overrides the TracingConfig resolved from the loader. Intended for tests or manual wiring without a YAML file.
func WithTracingOutput ¶
func WithTracingOutput(w io.Writer) TracingOption
WithTracingOutput sets the writer used by the stdout exporter. Defaults to os.Stdout when not provided. A nil writer is silently ignored.
Source Files