add some documentation around the metrics stability migration changes for clarity

Author: Han Kang

pkg/volume/util/metrics.go

@@ -30,39 +30,47 @@ const (
 	statusFailUnknown = "fail-unknown"
 )
 
+/*
+ * By default, all the following metrics are defined as falling under
+ * ALPHA stability level https://github.com/kubernetes/enhancements/blob/master/keps/sig-instrumentation/20190404-kubernetes-control-plane-metrics-stability.md#stability-classes)
+ *
+ * Promoting the stability level of the metric is a responsibility of the component owner, since it
+ * involves explicitly acknowledging support for the metric across multiple releases, in accordance with
+ * the metric stability policy.
+ */
 var storageOperationMetric = metrics.NewHistogramVec(
 	&metrics.HistogramOpts{
-		Name:    "storage_operation_duration_seconds",
-		Help:    "Storage operation duration",
-		Buckets: []float64{.1, .25, .5, 1, 2.5, 5, 10, 15, 25, 50, 120, 300, 600},
+		Name:           "storage_operation_duration_seconds",
+		Help:           "Storage operation duration",
+		Buckets:        []float64{.1, .25, .5, 1, 2.5, 5, 10, 15, 25, 50, 120, 300, 600},
 		StabilityLevel: metrics.ALPHA,
 	},
 	[]string{"volume_plugin", "operation_name"},
 )
 
 var storageOperationErrorMetric = metrics.NewCounterVec(
 	&metrics.CounterOpts{
-		Name: "storage_operation_errors_total",
-		Help: "Storage operation errors",
+		Name:           "storage_operation_errors_total",
+		Help:           "Storage operation errors",
 		StabilityLevel: metrics.ALPHA,
 	},
 	[]string{"volume_plugin", "operation_name"},
 )
 
 var storageOperationStatusMetric = metrics.NewCounterVec(
 	&metrics.CounterOpts{
-		Name: "storage_operation_status_count",
-		Help: "Storage operation return statuses count",
+		Name:           "storage_operation_status_count",
+		Help:           "Storage operation return statuses count",
 		StabilityLevel: metrics.ALPHA,
 	},
 	[]string{"volume_plugin", "operation_name", "status"},
 )
 
 var storageOperationEndToEndLatencyMetric = metrics.NewHistogramVec(
 	&metrics.HistogramOpts{
-		Name:    "volume_operation_total_seconds",
-		Help:    "Storage operation end to end duration in seconds",
-		Buckets: []float64{.1, .25, .5, 1, 2.5, 5, 10, 15, 25, 50, 120, 300, 600},
+		Name:           "volume_operation_total_seconds",
+		Help:           "Storage operation end to end duration in seconds",
+		Buckets:        []float64{.1, .25, .5, 1, 2.5, 5, 10, 15, 25, 50, 120, 300, 600},
 		StabilityLevel: metrics.ALPHA,
 	},
 	[]string{"plugin_name", "operation_name"},
@@ -73,6 +81,8 @@ func init() {
 }
 
 func registerMetrics() {
+	// legacyregistry is the internal k8s wrapper around the prometheus
+	// global registry, used specifically for metric stability enforcement
 	legacyregistry.MustRegister(storageOperationMetric)
 	legacyregistry.MustRegister(storageOperationErrorMetric)
 	legacyregistry.MustRegister(storageOperationStatusMetric)

staging/src/k8s.io/component-base/metrics/version.go

@@ -32,6 +32,6 @@ var (
 // RegisterBuildInfo registers the build and version info in a metadata metric in prometheus
 func RegisterBuildInfo(r KubeRegistry) {
 	info := version.Get()
-	buildInfo.WithLabelValues(info.Major, info.Minor, info.GitVersion, info.GitCommit, info.GitTreeState, info.BuildDate, info.GoVersion, info.Compiler, info.Platform).Set(1)
 	r.MustRegister(buildInfo)
+	buildInfo.WithLabelValues(info.Major, info.Minor, info.GitVersion, info.GitCommit, info.GitTreeState, info.BuildDate, info.GoVersion, info.Compiler, info.Platform).Set(1)
 }