Skip to content

Architecture & roadmap

transport-metrics is built to keep adding Prometheus instrumentation without ever becoming heavy to import. This page explains the shape and the plan.

Lean core, opt-in subpackages

The organising principle (shared with the toolkit's other modules) is that each heavy dependency lives behind a package boundary, so importing the core never pulls it. Go's linker only compiles imported packages, so the import you write is the switch.

Package Purpose Extra deps beyond core
metrics (core) registry, Go/process/build-info collectors, /metrics handler, guard middleware, HTTP request instrumentation, exemplar plumbing, RED/USE helpers prometheus/client_golang, go/errors, stdlib
metrics/server standalone metrics HTTP server go/transport
metrics/grpc gRPC server interceptors google.golang.org/grpc
metrics/otel OpenMetrics exemplar trace source go.opentelemetry.io/otel/trace

A depfootprint_test.go guard asserts the core graph (go list -deps .) is free of go/transport, gRPC, OTel, go-tool-base and any CLI framework, so a tool that imports the core for a plain /metrics endpoint links none of them.

Why the core needs no go/transport

The guard middleware is the standard Go signature, func(http.Handler) http.Handler. The core accepts that bare type, so a caller passes go/transport's AuthMiddleware (or any middleware) without the core depending on go/transport. Only the standalone server genuinely needs transport's lifecycle, so only metrics/server imports it.

No dependency cycle

go/transport's server takes a caller-owned mux (NewServer(ctx, settings, handler, …)). The tool mounts metrics onto its mux and passes it to the server; go/transport never imports transport-metrics. Request instrumentation works the same way: the module produces middleware the tool applies through transport's existing WithMiddleware. A cycle could only arise by making go/transport depend on this module (a built-in metrics option), which is deliberately avoided because it would also drag Prometheus into transport core.

Roadmap

Delivered in reviewable minors, each independently useful.

What has shipped

  • v0.1.0: Endpoint & runtime. /metrics, Go/process/build-info collectors, pprof, the auth-guard hook, custom collectors, and the standalone metrics/server.
  • v0.2.0: Request instrumentation. HTTP middleware with route-template labels (cardinality-safe) + metrics/grpc interceptors, and OpenMetrics exemplars via a pluggable trace source (metrics/otel).
  • v0.3.0: RED/USE helpers. Ready-made instrument sets for databases, caches, circuit breakers and queues, plus the generic business-logic Operations wrapper.
  • v0.4.0: Loopback by default. The standalone metrics/server binds 127.0.0.1 unless told otherwise. This was a behaviour change: it previously bound all interfaces. See the migration note.
  • v0.5.0: Shared errors module. Errors come from gitlab.com/phpboyscout/go/errors, the toolkit's shared errors module. It replaced cockroachdb/errors, so a consumer that inspected returned errors with cockroachdb's helpers must switch to go/errors or the standard errors package.

What has not

  • Client-side instrumentation of outbound HTTP and gRPC calls. Not started; see Limitations for what to use meanwhile.
  • Back-porting the RED/USE ergonomics to the OTel go/observability modules, so both families feel the same. Tracked there, not here.

Anything not on this list, and not in the module today, is best treated as absent rather than imminent. Limitations is the full inventory.