📖 document exposed metrics (alternative)

Export the variables defining the metrics in this package, and document
them, to follow the pattern established by `pkg/internal/controller/metrics`
and `pkg/webhook/internal/metrics`.

Author: djzager

pkg/metrics/client_go_adapter.go

@@ -32,21 +32,21 @@ import (
 var (
 	// client metrics
 
-	requestLatency = prometheus.NewHistogramVec(
-		prometheus.HistogramOpts{
-			Name:    "rest_client_request_latency_seconds",
-			Help:    "Request latency in seconds. Broken down by verb and URL.",
-			Buckets: prometheus.ExponentialBuckets(0.001, 2, 10),
-		},
-		[]string{"verb", "url"},
+	// RequestLatency is a prometheus metric which tracks the latency of requests
+	// broken down by verb and URL.
+	RequestLatency = prometheus.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "rest_client_request_latency_seconds",
+		Help:    "Request latency in seconds. Broken down by verb and URL.",
+		Buckets: prometheus.ExponentialBuckets(0.001, 2, 10),
+	}, []string{"verb", "url"},
 	)
 
-	requestResult = prometheus.NewCounterVec(
-		prometheus.CounterOpts{
-			Name: "rest_client_requests_total",
-			Help: "Number of HTTP requests, partitioned by status code, method, and host.",
-		},
-		[]string{"code", "method", "host"},
+	// RequestResult is a prometheus metric that tracks the number of HTTP requests
+	// broken down by status code, method, and host.
+	RequestResult = prometheus.NewCounterVec(prometheus.CounterOpts{
+		Name: "rest_client_requests_total",
+		Help: "Number of HTTP requests, partitioned by status code, method, and host.",
+	}, []string{"code", "method", "host"},
 	)
 
 	// reflector metrics
@@ -56,49 +56,65 @@ var (
 
 	reflectorSubsystem = "reflector"
 
-	listsTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+	// ListsTotal is a prometheus metric tracking the total number of API lists done
+	// by the reflectors.
+	ListsTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
 		Subsystem: reflectorSubsystem,
 		Name:      "lists_total",
 		Help:      "Total number of API lists done by the reflectors",
 	}, []string{"name"})
 
-	listsDuration = prometheus.NewSummaryVec(prometheus.SummaryOpts{
+	// ListsDuration is a prometheus metric tracking how long an API list takes to
+	// return and decode for the reflectors.
+	ListsDuration = prometheus.NewSummaryVec(prometheus.SummaryOpts{
 		Subsystem: reflectorSubsystem,
 		Name:      "list_duration_seconds",
 		Help:      "How long an API list takes to return and decode for the reflectors",
 	}, []string{"name"})
 
-	itemsPerList = prometheus.NewSummaryVec(prometheus.SummaryOpts{
+	// ItemsPerList is a prometheus metric tracking how many items an API list returns
+	// to the reflectors.
+	ItemsPerList = prometheus.NewSummaryVec(prometheus.SummaryOpts{
 		Subsystem: reflectorSubsystem,
 		Name:      "items_per_list",
 		Help:      "How many items an API list returns to the reflectors",
 	}, []string{"name"})
 
-	watchesTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+	// WatchesTotal is a prometheus metric tracking the total number of API watches
+	// done by the reflectors.
+	WatchesTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
 		Subsystem: reflectorSubsystem,
 		Name:      "watches_total",
 		Help:      "Total number of API watches done by the reflectors",
 	}, []string{"name"})
 
-	shortWatchesTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
+	// ShortWatchesTotal is a prometheus metric tracking the total number of short
+	// API watches done by the reflectors.
+	ShortWatchesTotal = prometheus.NewCounterVec(prometheus.CounterOpts{
 		Subsystem: reflectorSubsystem,
 		Name:      "short_watches_total",
 		Help:      "Total number of short API watches done by the reflectors",
 	}, []string{"name"})
 
-	watchDuration = prometheus.NewSummaryVec(prometheus.SummaryOpts{
+	// WatchDuration is a prometheus metric tracking how long an API watch takes
+	// to return and decode for the reflectors.
+	WatchDuration = prometheus.NewSummaryVec(prometheus.SummaryOpts{
 		Subsystem: reflectorSubsystem,
 		Name:      "watch_duration_seconds",
 		Help:      "How long an API watch takes to return and decode for the reflectors",
 	}, []string{"name"})
 
-	itemsPerWatch = prometheus.NewSummaryVec(prometheus.SummaryOpts{
+	// ItemsPerWatch is a prometheus metric tracking how many items an API watch
+	// returns to the reflectors.
+	ItemsPerWatch = prometheus.NewSummaryVec(prometheus.SummaryOpts{
 		Subsystem: reflectorSubsystem,
 		Name:      "items_per_watch",
 		Help:      "How many items an API watch returns to the reflectors",
 	}, []string{"name"})
 
-	lastResourceVersion = prometheus.NewGaugeVec(prometheus.GaugeOpts{
+	// LastResourceVersion is a prometheus metric tracking the last resource version
+	// seen for the reflectors.
+	LastResourceVersion = prometheus.NewGaugeVec(prometheus.GaugeOpts{
 		Subsystem: reflectorSubsystem,
 		Name:      "last_resource_version",
 		Help:      "Last resource version seen for the reflectors",
@@ -113,23 +129,23 @@ func init() {
 // registerClientMetrics sets up the client latency metrics from client-go
 func registerClientMetrics() {
 	// register the metrics with our registry
-	Registry.MustRegister(requestLatency)
-	Registry.MustRegister(requestResult)
+	Registry.MustRegister(RequestLatency)
+	Registry.MustRegister(RequestResult)
 
 	// register the metrics with client-go
-	clientmetrics.Register(&latencyAdapter{metric: requestLatency}, &resultAdapter{metric: requestResult})
+	clientmetrics.Register(&latencyAdapter{metric: RequestLatency}, &resultAdapter{metric: RequestResult})
 }
 
 // registerReflectorMetrics sets up reflector (reconcile) loop metrics
 func registerReflectorMetrics() {
-	Registry.MustRegister(listsTotal)
-	Registry.MustRegister(listsDuration)
-	Registry.MustRegister(itemsPerList)
-	Registry.MustRegister(watchesTotal)
-	Registry.MustRegister(shortWatchesTotal)
-	Registry.MustRegister(watchDuration)
-	Registry.MustRegister(itemsPerWatch)
-	Registry.MustRegister(lastResourceVersion)
+	Registry.MustRegister(ListsTotal)
+	Registry.MustRegister(ListsDuration)
+	Registry.MustRegister(ItemsPerList)
+	Registry.MustRegister(WatchesTotal)
+	Registry.MustRegister(ShortWatchesTotal)
+	Registry.MustRegister(WatchDuration)
+	Registry.MustRegister(ItemsPerWatch)
+	Registry.MustRegister(LastResourceVersion)
 
 	reflectormetrics.SetReflectorMetricsProvider(reflectorMetricsProvider{})
 }
@@ -165,33 +181,33 @@ func (r *resultAdapter) Increment(code, method, host string) {
 type reflectorMetricsProvider struct{}
 
 func (reflectorMetricsProvider) NewListsMetric(name string) reflectormetrics.CounterMetric {
-	return listsTotal.WithLabelValues(name)
+	return ListsTotal.WithLabelValues(name)
 }
 
 func (reflectorMetricsProvider) NewListDurationMetric(name string) reflectormetrics.SummaryMetric {
-	return listsDuration.WithLabelValues(name)
+	return ListsDuration.WithLabelValues(name)
 }
 
 func (reflectorMetricsProvider) NewItemsInListMetric(name string) reflectormetrics.SummaryMetric {
-	return itemsPerList.WithLabelValues(name)
+	return ItemsPerList.WithLabelValues(name)
 }
 
 func (reflectorMetricsProvider) NewWatchesMetric(name string) reflectormetrics.CounterMetric {
-	return watchesTotal.WithLabelValues(name)
+	return WatchesTotal.WithLabelValues(name)
 }
 
 func (reflectorMetricsProvider) NewShortWatchesMetric(name string) reflectormetrics.CounterMetric {
-	return shortWatchesTotal.WithLabelValues(name)
+	return ShortWatchesTotal.WithLabelValues(name)
 }
 
 func (reflectorMetricsProvider) NewWatchDurationMetric(name string) reflectormetrics.SummaryMetric {
-	return watchDuration.WithLabelValues(name)
+	return WatchDuration.WithLabelValues(name)
 }
 
 func (reflectorMetricsProvider) NewItemsInWatchMetric(name string) reflectormetrics.SummaryMetric {
-	return itemsPerWatch.WithLabelValues(name)
+	return ItemsPerWatch.WithLabelValues(name)
 }
 
 func (reflectorMetricsProvider) NewLastResourceVersionMetric(name string) reflectormetrics.GaugeMetric {
-	return lastResourceVersion.WithLabelValues(name)
+	return LastResourceVersion.WithLabelValues(name)
 }

pkg/metrics/doc.go

@@ -15,51 +15,6 @@ limitations under the License.
 */
 
 /*
-Package metrics contains controller related metrics utilities.
-
-Client Metrics
-
-"rest_client_request_latency_seconds" - Request latency in seconds. Broken down by verb and URL.
-
-"rest_client_requests_total" - Number of HTTP requests, partitioned by status code, method, and host.
-
-Reflector Metrics
-
-"reflector_lists_total" - Total number of API lists done by the reflectors.
-
-"reflector_list_duration_seconds" - How long an API list takes to return and decode for the reflectors.
-
-"reflector_items_per_list" - How many items an API list returns to the reflectors.
-
-"reflector_watches_total" - Total number of API watches done by the reflectors.
-
-"reflector_short_watches_total" - Total number of short API watches done by the reflectors.
-
-"reflector_watch_duration_seconds" - How long an API watch takes to return and decode for the reflectors.
-
-"reflector_items_per_watch" - How many items an API watch returns to the reflectors.
-
-"reflector_last_resource_version" - Last resource version seen for the reflectors.
-
-Workqueue Metrics
-
-"workqueue_depth" - Current depth of workqueue
-
-"workqueue_adds_total" - Total number of adds handled by workqueue.
-
-"workqueue_queue_duration_seconds" - How long in seconds an item stays in workqueue before being requested.
-
-"workqueue_work_duration_seconds" - How long in seconds processing an item from workqueue takes.
-
-"workqueue_unfinished_work_seconds" - How many seconds of work has done that 
-is in progress and hasn't been observed by work_duration. Large 
-values indicate stuck threads. One can deduce the number of stuck
-threads by observing the rate at which this increases.
-
-"workqueue_longest_running_processor_seconds" - How many seconds has the longest running 
-processor for workqueue been running.
-
-"workqueue_retries_total" - Total number of retries handled by workqueue.
-
+Package metrics contains controller related metrics utilities
 */
 package metrics

pkg/metrics/listener.go

@@ -19,8 +19,12 @@ package metrics
 import (
 	"fmt"
 	"net"
+
+	logf "sigs.k8s.io/controller-runtime/pkg/internal/log"
 )
 
+var log = logf.RuntimeLog.WithName("metrics")
+
 // DefaultBindAddress sets the default bind address for the metrics listener
 // The metrics is on by default.
 var DefaultBindAddress = ":8080"