README
¶
obs
standardized OTel configuration - nothing of interest
Documentation
¶
Overview ¶
Package obs is the atomdrift shared OpenTelemetry wiring.
Services call Init once during startup with a Config (zero values fall back to OTEL_* env vars), defer the returned shutdown into their signal-handling path, and then use Meter, Tracer, Job, and the HTTP helpers as needed.
Each OTLP signal (metrics, traces, logs) is enabled only when its endpoint is configured — either via [Config.Endpoint] or via the standard OTEL_EXPORTER_OTLP_*_ENDPOINT env vars. The Prometheus scrape handler exposed by MetricsHandler is always available so callers can mount /_/metrik regardless of OTLP wiring.
Index ¶
- func Init(ctx context.Context, cfg Config) (func(context.Context) error, error)
- func Job(ctx context.Context, name string, fn func(context.Context) error) error
- func Meter() metric.Meter
- func MetricsHandler() http.Handler
- func Middleware(next http.Handler) http.Handler
- func NoOp() func(context.Context) error
- func OTLPSlogHandler(serviceName string) slog.Handler
- func PoolStats(name string, pool *pgxpool.Pool) error
- func TeeSlog(base slog.Handler, serviceName string) slog.Handler
- func Tracer() trace.Tracer
- type Config
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Init ¶
Init wires up OpenTelemetry for the calling service. It is safe to call exactly once per process; a second call returns an error.
Init installs global trace, meter, and logger providers; replaces slog.Default with a handler that tees to stderr and the OTel log pipeline; and enables push exporters only for signals whose endpoint is configured. The returned shutdown should be invoked with a deadline-bearing context during graceful termination.
func Job ¶
Job runs fn inside a span named after name and records both the duration histogram and an outcome-labeled counter. The returned error is fn's error verbatim, after being recorded on the span.
Safe to call before Init: if instruments are unset, Job still invokes fn but emits no telemetry.
func Meter ¶
Meter returns a Meter scoped to the obs package. Callers that want a service-scoped meter should use otel.Meter("their-package") instead.
func MetricsHandler ¶
MetricsHandler returns the Prometheus scrape handler backed by the OTel meter provider. Mount it at /_/metrik on the service's existing mux. Responds 503 until Init has run.
func Middleware ¶
Middleware wraps an http.Handler with OTel HTTP server instrumentation: trace propagation, a span per request, and the standard http.server.request.duration / http.server.active_requests metrics. The span name is derived from the matched route pattern when the underlying handler is an http.ServeMux (Go 1.22+); callers using third-party routers should pass a route-aware wrapper.
Safe to call before Init — the underlying otelhttp uses the global tracer/meter, which are no-op until Init replaces them.
func NoOp ¶
NoOp returns a shutdown that does nothing. Useful in tests so test binaries don't try to dial an OTLP endpoint.
func OTLPSlogHandler ¶
OTLPSlogHandler returns just the OTel-bridge slog handler — records passed through it are exported via the global LoggerProvider. Useful for services with bespoke logging chains (e.g. file + stderr fan-out) that want to add OTLP as one more sink. Compose it into your own fan-out and call slog.SetDefault yourself; pair with Config.DisableSlog = true so Init doesn't fight you.
func PoolStats ¶
PoolStats wires async gauges that expose pgxpool connection-pool counters under db.pool.*. Call once after the pool is created. Multiple pools may be registered with distinct names (e.g. "hopper", "replica"); the name becomes a "pool" attribute.
Safe to call before Init: the global no-op meter accepts the instrument creation and the callbacks do nothing useful until Init installs the real provider.
Types ¶
type Config ¶
type Config struct {
// ServiceName is the OTel service.name resource attribute. Required.
ServiceName string
// ServiceVersion is the OTel service.version resource attribute.
// If empty, falls back to debug.ReadBuildInfo() then "devel".
ServiceVersion string
// Environment is the OTel deployment.environment resource attribute.
// If empty, falls back to OTEL_DEPLOYMENT_ENVIRONMENT then "dev".
Environment string
// Endpoint is the OTLP/HTTP base endpoint applied to any signal
// that does not have a signal-specific OTEL_EXPORTER_OTLP_*_ENDPOINT
// override. If empty and no per-signal env vars are set, OTLP push
// is disabled (the SDK still installs no-op providers).
Endpoint string
// Insecure forces http:// when true. If false, the URL scheme of the
// resolved endpoint decides.
Insecure bool
// SampleRatio is the trace head-sampling ratio (0.0–1.0). If zero,
// falls back to OTEL_TRACES_SAMPLER_ARG, then 0.1.
SampleRatio float64
// DisableSlog skips Init's slog.SetDefault. Use this when the
// caller has its own fan-out chain (e.g. stderr + file + OTLP) and
// wants to compose [OTLPSlogHandler] in itself.
DisableSlog bool
}
Config controls obs initialization. The zero value is invalid (ServiceName is required); all other fields fall back to env vars or sensible defaults.
Source Files
Directories