observability

Documentation

Overview

Package observability bootstraps Aileron's OpenTelemetry tracer provider and propagator. Issue #390 Phase 7 ships this as foundation: external callers can include `traceparent` on requests to Aileron and have it propagated through; span emission at action, connector, capability, and approval boundaries lands in follow-up PRs once the audit-log file rotation work converges and the file exporter can share the rotating writer.

The shape of Init is intentionally narrow: it returns a Provider whose Provider.Shutdown flushes pending spans. Code inside the request path uses otel.Tracer to acquire a tracer and propagation.TraceContext for W3C propagation — both come from the global registrations Init performs.

Index

• func HTTPMiddleware(spanNameFn func(*http.Request) string) func(http.Handler) http.Handler
• type Provider
  • func Init(cfg *config.ObservabilityConfig, log *slog.Logger) *Provider
  • func (p *Provider) Shutdown(ctx context.Context) error

Functions

func HTTPMiddleware

func HTTPMiddleware(spanNameFn func(*http.Request) string) func(http.Handler) http.Handler

HTTPMiddleware returns an HTTP middleware that:

1. Extracts incoming W3C TraceContext (`traceparent` / `tracestate`) into the request context — when an upstream caller passed one, downstream spans become children of that trace and the agent's end-to-end view stays coherent.
2. Starts an HTTP server-root span named per the supplied spanNameFn. The span ends when the handler returns; status defaults to OK.

When tracing is in no-op mode (the daemon-startup default) the extraction is still performed — propagation is cheap, useful, and orthogonal to whether *this* process emits — and the no-op tracer's Start returns a span whose End is a no-op. Net runtime cost: a header lookup and a few interface calls per request.

spanNameFn shapes the span's name from the request. Callers pass a fixed-string returner like `"aileron.actions.run"` or a templater that emits `"GET /v1/actions"`. Keeping it a function lets the gateway-handler-specific names land in their respective handlers without leaking handler details into this package.

Types

type Provider

type Provider struct {
	trace.TracerProvider
	// contains filtered or unexported fields
}

Provider wraps a trace.TracerProvider with a Provider.Shutdown hook the daemon calls at process end. Embedding rather than aliasing lets callers pass it anywhere a TracerProvider is expected.

func Init

func Init(cfg *config.ObservabilityConfig, log *slog.Logger) *Provider

Init constructs the tracer provider, installs it as the OTel global, and registers the W3C TraceContext propagator. Callers should defer Shutdown on the returned Provider to flush at process end.

When cfg.OTelEnabled is false (the default) Init installs a no-op provider — there is no SDK overhead and exporters are never constructed. The propagator is installed unconditionally so `traceparent` on inbound requests is parsed regardless; this lets the gateway pass a coherent context downstream even before Aileron itself starts emitting spans, and it costs nothing when no spans are recorded.

log may be nil; warnings about exporter construction failures are routed to slog.Default in that case. An exporter failure degrades gracefully to no-op rather than failing daemon startup — the Aileron HTTP server should keep serving requests when its telemetry sidecar is misconfigured.

func (*Provider) Shutdown

func (p *Provider) Shutdown(ctx context.Context) error

Shutdown flushes any pending spans and releases exporter resources. Safe to call when the provider was created in no-op mode — the call short-circuits and returns nil.