metrics

metrics defines a backend-agnostic instrumentation contract for Go services.

Table of contents

Part of nurago, a collection of independent Go packages for backend services.

import "github.com/tecnickcom/nurago/pkg/metrics"

Package metrics defines a backend-agnostic instrumentation contract for Go services.

The Client interface is an abstraction over common instrumentation points used across services:

  • SQL opening and DB instrumentation
  • inbound HTTP handler instrumentation
  • outbound HTTP round-tripper instrumentation
  • metrics endpoint handler
  • application-level counters (log levels and error taxonomy)

The Default implementation is minimal:

  • it behaves as a no-op for instrumentation methods,
  • it still returns a valid SQL connection from Default.SqlOpen, and
  • it exposes a health-style metrics handler that returns “OK”.

This makes instrumentation optional and allows applications to run without a configured metrics backend while keeping a consistent API.

Backends

Concrete implementations are available in sibling packages:

  • github.com/tecnickcom/nurago/pkg/metrics/statsd
  • github.com/tecnickcom/nurago/pkg/metrics/prometheus
  • github.com/tecnickcom/nurago/pkg/metrics/opentel

When To Use

  • You want to swap Prometheus for OpenTelemetry without touching handler code.
  • Tests should run against a no-op implementation rather than a live backend.
  • Library code needs to emit metrics without dictating the backend to its callers.

Example

// Default is a no-op implementation, useful in tests and in builds that
// ship without a metrics backend. Swapping in
// metrics/prometheus.New, metrics/statsd.New, or metrics/opentel.New
// changes nothing else in the service.
svc := &service{mtr: &metrics.Default{}}

srv := httptest.NewServer(svc.routes())
defer srv.Close()

req, err := http.NewRequestWithContext(context.TODO(), http.MethodGet, srv.URL+"/users/42", nil)
if err != nil {
	fmt.Println(err)

	return
}

resp, err := srv.Client().Do(req)
if err != nil {
	fmt.Println(err)

	return
}

defer func() { _ = resp.Body.Close() }()

svc.mtr.IncErrorCounter("user", "read", "404")
svc.mtr.IncLogLevelCounter("error")

fmt.Println(resp.StatusCode, svc.mtr.Close())

// Output:
// 200 <nil>

Full source is in example_metrics_test.go. More runnable examples are on pkg.go.dev.

Dependencies

This package reaches no external module: it uses only the Go standard library.