observe

func NewHTTPHandler ¶

func NewHTTPHandler(handler http.Handler, operation string) http.Handler

NewHTTPHandler wraps the given http.Handler with OpenTelemetry HTTP instrumentation, creating spans for each inbound request (OTEL-01). The operation parameter becomes the span name prefix (e.g. "api" or "html").

func NewHandler ¶

func NewHandler(cfg config.ObserveConfig) slog.Handler

NewHandler returns an environment-aware slog handler. When cfg.LogFormat is "json" (or FORGE_ENV=production forces it), JSON output is written to stderr for structured log aggregation. Otherwise a human-readable text handler is returned for local development.

func PGXTracer ¶

func PGXTracer() *otelpgx.Tracer

PGXTracer returns an otelpgx.Tracer that can be passed to pgxpool.Config as a tracer for automatic database query span creation (OTEL-01 DB traces).

func Setup ¶

func Setup(ctx context.Context, cfg config.ObserveConfig, serviceName string) (shutdown func(context.Context) error, err error)

Setup bootstraps the OpenTelemetry SDK, setting the global TracerProvider and MeterProvider. It returns a shutdown function that callers must invoke (usually via defer) to flush and stop all exporters gracefully.

When cfg.OTLPEndpoint is non-empty, traces are exported via OTLP HTTP to that endpoint. Otherwise traces are written to stdout (pretty-printed) for local development visibility.

Metrics are always exported via the Prometheus bridge so that the admin server /metrics endpoint can serve them (OTEL-02).

func StartAdminServer ¶

func StartAdminServer(ctx context.Context, cfg config.AdminConfig) *http.Server

StartAdminServer creates and starts a dedicated admin/ops HTTP server on the port specified in cfg (default 9090). It exposes three operational endpoints:

• /metrics — Prometheus metrics (via OTel-Prometheus bridge, OTEL-02)
• /healthz — JSON health check with build version info (OTEL-03)
• /debug/pprof/ — Go pprof profiling endpoints (admin-only, not on public mux)

The server runs in a goroutine. The caller is responsible for calling Shutdown on the returned *http.Server during application teardown.