95 lines
3.0 KiB
Markdown
95 lines
3.0 KiB
Markdown
# 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).
|