# 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).