Add obsx library

README.md

@@ -0,0 +1,94 @@
+# obsx
+
+Observability library for Go providing metrics (Prometheus) and tracing (OpenTelemetry) setup with consistent defaults. Creates a Prometheus registry with process/Go collectors, a metrics factory with namespace/subsystem scoping, and an OTLP gRPC tracer provider with configurable sampling.
+
+```
+go get git.codelab.vc/pkg/obsx
+```
+
+## Quick start
+
+```go
+// Tracing
+shutdown, err := obsx.SetupTracer(ctx, obsx.TracerConfig{
+    ServiceName:    "my-service",
+    ServiceVersion: "1.0.0",
+    Endpoint:       "localhost:4317",
+    Sampler:        1.0, // sample everything
+})
+if err != nil {
+    log.Fatal(err)
+}
+defer shutdown(ctx)
+
+// Metrics
+metrics := obsx.NewMetrics(obsx.MetricsConfig{
+    Namespace: "myapp",
+    Subsystem: "http",
+})
+reqCounter := metrics.Counter("requests_total", "Total HTTP requests", "method", "status")
+latency := metrics.Histogram("request_duration_seconds", "Request latency", nil, "method")
+
+http.Handle("/metrics", metrics.Handler())
+```
+
+## Components
+
+| Component | What it does |
+|-----------|-------------|
+| `SetupTracer` | Initializes an OpenTelemetry tracer provider with OTLP gRPC exporter, sets it as the global provider. |
+| `StartSpan` | Convenience wrapper that starts a span using the global tracer provider. |
+| `Metrics` | Factory for creating Prometheus metrics with consistent namespace/subsystem naming. |
+| `TracerConfig` | Configures the tracer: service name, version, OTLP endpoint, sampling ratio. |
+| `MetricsConfig` | Configures the metrics factory: namespace and subsystem. |
+
+## Tracing
+
+`SetupTracer` creates an OTLP gRPC exporter, builds a tracer provider with batched span export and ratio-based sampling, and registers it as the global `otel.TracerProvider`. Returns a shutdown function that must be called on application exit.
+
+```go
+shutdown, err := obsx.SetupTracer(ctx, obsx.TracerConfig{
+    ServiceName: "orders-api",
+    Endpoint:    "jaeger:4317",
+    Sampler:     0.1, // sample 10%
+})
+defer shutdown(ctx)
+```
+
+Start spans with the convenience helper:
+
+```go
+ctx, span := obsx.StartSpan(ctx, "process-order")
+defer span.End()
+```
+
+## Metrics
+
+`NewMetrics` creates a fresh Prometheus registry (isolated from the global default) pre-loaded with process and Go runtime collectors. All metrics created through the factory inherit the configured namespace and subsystem.
+
+```go
+m := obsx.NewMetrics(obsx.MetricsConfig{Namespace: "myapp", Subsystem: "db"})
+
+// Counter
+queries := m.Counter("queries_total", "Total queries executed", "operation")
+queries.WithLabelValues("select").Inc()
+
+// Histogram (nil buckets = prometheus.DefBuckets)
+latency := m.Histogram("query_duration_seconds", "Query latency", nil, "operation")
+
+// Gauge
+conns := m.Gauge("connections_active", "Active connections", "pool")
+
+// HTTP handler for /metrics endpoint
+http.Handle("/metrics", m.Handler())
+```
+
+Access the underlying registry directly:
+
+```go
+registry := m.Registry()
+```
+
+## Requirements
+
+Go 1.24+, [OpenTelemetry Go](https://opentelemetry.io/docs/languages/go/), [Prometheus client_golang](https://github.com/prometheus/client_golang).