metrics: add tests and documentation

metricsserver/metrics.go

@@ -1,3 +1,8 @@
+// Package metricsserver provides a standalone HTTP server for exposing Prometheus metrics.
+//
+// This package implements a dedicated metrics server that exposes application metrics
+// via HTTP. It uses a custom Prometheus registry to avoid conflicts with other metric
+// collectors and provides graceful shutdown capabilities.
 package metricsserver
 
 import (
@@ -13,10 +18,13 @@ import (
 	"go.ntppool.org/common/logger"
 )
 
+// Metrics provides a custom Prometheus registry and HTTP handlers for metrics exposure.
+// It isolates application metrics from the default global registry.
 type Metrics struct {
 	r *prometheus.Registry
 }
 
+// New creates a new Metrics instance with a custom Prometheus registry.
 func New() *Metrics {
 	r := prometheus.NewRegistry()
 
@@ -27,10 +35,13 @@ func New() *Metrics {
 	return m
 }
 
+// Registry returns the custom Prometheus registry.
+// Use this to register your application's metrics collectors.
 func (m *Metrics) Registry() *prometheus.Registry {
 	return m.r
 }
 
+// Handler returns an HTTP handler for the /metrics endpoint with OpenMetrics support.
 func (m *Metrics) Handler() http.Handler {
 	log := logger.NewStdLog("prom http", false, nil)
 
@@ -41,9 +52,8 @@ func (m *Metrics) Handler() http.Handler {
 	})
 }
 
-// ListenAndServe starts a goroutine with a server running on
-// the specified port. The server will shutdown and return when
-// the provided context is done
+// ListenAndServe starts a metrics server on the specified port and blocks until ctx is done.
+// The server exposes the metrics handler and shuts down gracefully when the context is cancelled.
 func (m *Metrics) ListenAndServe(ctx context.Context, port int) error {
 	log := logger.Setup()