Skip to content

Architecture & roadmap

transport-metrics is built to grow into a comprehensive Prometheus instrumentation module 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, 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 is the same — 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 — it would also drag Prometheus into transport core.

Roadmap

Delivered in reviewable minors, each independently useful:

  • 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 (this release). 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 (this release). Ready-made instrument sets for databases, caches, circuit breakers and queues, plus the generic business-logic Operations wrapper.
  • Follow-up. Back-porting the RED/USE ergonomics to the OTel go/observability modules so both families feel the same; optional client-side instrumentation.