stats/otel: a79 scaffolding to register an async gauge metric and api to record it- part 1 (#8731)

Addresses
https://github.com/grpc/proposal/blob/master/A79-non-per-call-metrics-architecture.md
This PR creates scaffolding to register an async gauge metric. It adds
an AsyncMetricsRecorder interface that defines the api for recording an
int64 async gauge metric.

RELEASE NOTES:
* stats/otel: Add scaffolding to register an async gauge metric. Add an
AsyncMetricsRecorder interface that defines the api for recording an
int64 async gauge metric.

Author: mbissa

experimental/stats/metricregistry.go

@@ -76,6 +76,7 @@ const (
 	MetricTypeFloatHisto
 	MetricTypeIntGauge
 	MetricTypeIntUpDownCount
+	MetricTypeIntAsyncGauge
 )
 
 // Int64CountHandle is a typed handle for a int count metric. This handle
@@ -172,6 +173,30 @@ func (h *Int64GaugeHandle) Record(recorder MetricsRecorder, incr int64, labels .
 	recorder.RecordInt64Gauge(h, incr, labels...)
 }
 
+// AsyncMetric is a marker interface for asynchronous metric types.
+type AsyncMetric interface {
+	isAsync()
+	Descriptor() *MetricDescriptor
+}
+
+// Int64AsyncGaugeHandle is a typed handle for an int gauge metric. This handle is
+// passed at the recording point in order to know which metric to record on.
+type Int64AsyncGaugeHandle MetricDescriptor
+
+// isAsync implements the AsyncMetric interface.
+func (h *Int64AsyncGaugeHandle) isAsync() {}
+
+// Descriptor returns the int64 gauge handle typecast to a pointer to a
+// MetricDescriptor.
+func (h *Int64AsyncGaugeHandle) Descriptor() *MetricDescriptor {
+	return (*MetricDescriptor)(h)
+}
+
+// Record records the int64 gauge value on the metrics recorder provided.
+func (h *Int64AsyncGaugeHandle) Record(recorder AsyncMetricsRecorder, value int64, labels ...string) {
+	recorder.RecordInt64AsyncGauge(h, value, labels...)
+}
+
 // registeredMetrics are the registered metric descriptor names.
 var registeredMetrics = make(map[string]bool)
 
@@ -282,6 +307,20 @@ func RegisterInt64UpDownCount(descriptor MetricDescriptor) *Int64UpDownCountHand
 	return (*Int64UpDownCountHandle)(descPtr)
 }
 
+// RegisterInt64AsyncGauge registers the metric description onto the global registry.
+// It returns a typed handle to use for recording data.
+//
+// NOTE: this function must only be called during initialization time (i.e. in
+// an init() function), and is not thread-safe. If multiple metrics are
+// registered with the same name, this function will panic.
+func RegisterInt64AsyncGauge(descriptor MetricDescriptor) *Int64AsyncGaugeHandle {
+	registerMetric(descriptor.Name, descriptor.Default)
+	descriptor.Type = MetricTypeIntAsyncGauge
+	descPtr := &descriptor
+	metricsRegistry[descriptor.Name] = descPtr
+	return (*Int64AsyncGaugeHandle)(descPtr)
+}
+
 // snapshotMetricsRegistryForTesting snapshots the global data of the metrics
 // registry. Returns a cleanup function that sets the metrics registry to its
 // original state.

experimental/stats/metricregistry_test.go

@@ -117,6 +117,14 @@ func (s) TestMetricRegistry(t *testing.T) {
 		OptionalLabels: []string{"int up down counter optional label"},
 		Default:        false,
 	})
+	intAsyncGaugeHandle1 := RegisterInt64AsyncGauge(MetricDescriptor{
+		Name:           "simple async gauge",
+		Description:    "the most recent int emitted by test",
+		Unit:           "int",
+		Labels:         []string{"int async gauge label"},
+		OptionalLabels: []string{"int async gauge optional label"},
+		Default:        false,
+	})
 
 	fmr := newFakeMetricsRecorder(t)
 
@@ -155,9 +163,13 @@ func (s) TestMetricRegistry(t *testing.T) {
 	if got := fmr.intValues[intGaugeHandle1.Descriptor()]; got != 7 {
 		t.Fatalf("fmr.intValues[intGaugeHandle1.MetricDescriptor] got %v, want: %v", got, 7)
 	}
+	intAsyncGaugeHandle1.Record(fmr, 9, []string{"some label value", "some optional label value"}...)
+	if got := fmr.intValues[intAsyncGaugeHandle1.Descriptor()]; got != 9 {
+		t.Fatalf("fmr.intValues[intAsyncGaugeHandle1.MetricDescriptor] got %v, want: %v", got, 9)
+	}
 }
 
-func TestUpDownCounts(t *testing.T) {
+func (s) TestUpDownCounts(t *testing.T) {
 	cleanup := snapshotMetricsRegistryForTesting()
 	defer cleanup()
 
@@ -182,7 +194,7 @@ func TestUpDownCounts(t *testing.T) {
 // TestNumerousIntCounts tests numerous int count metrics registered onto the
 // metric registry. A component (simulated by test) should be able to record on
 // the different registered int count metrics.
-func TestNumerousIntCounts(t *testing.T) {
+func (s) TestNumerousIntCounts(t *testing.T) {
 	cleanup := snapshotMetricsRegistryForTesting()
 	defer cleanup()
 
@@ -257,18 +269,6 @@ func newFakeMetricsRecorder(t *testing.T) *fakeMetricsRecorder {
 		intValues:   make(map[*MetricDescriptor]int64),
 		floatValues: make(map[*MetricDescriptor]float64),
 	}
-
-	for _, desc := range metricsRegistry {
-		switch desc.Type {
-		case MetricTypeIntCount:
-		case MetricTypeIntHisto:
-		case MetricTypeIntGauge:
-			fmr.intValues[desc] = 0
-		case MetricTypeFloatCount:
-		case MetricTypeFloatHisto:
-			fmr.floatValues[desc] = 0
-		}
-	}
 	return fmr
 }
 
@@ -308,3 +308,8 @@ func (r *fakeMetricsRecorder) RecordInt64UpDownCount(handle *Int64UpDownCountHan
 	verifyLabels(r.t, handle.Descriptor().Labels, handle.Descriptor().OptionalLabels, labels)
 	r.intValues[handle.Descriptor()] += incr
 }
+
+func (r *fakeMetricsRecorder) RecordInt64AsyncGauge(handle *Int64AsyncGaugeHandle, incr int64, labels ...string) {
+	verifyLabels(r.t, handle.Descriptor().Labels, handle.Descriptor().OptionalLabels, labels)
+	r.intValues[handle.Descriptor()] += incr
+}

experimental/stats/metrics.go

@@ -43,6 +43,13 @@ type MetricsRecorder interface {
 	RecordInt64UpDownCount(handle *Int64UpDownCountHandle, incr int64, labels ...string)
 }
 
+// AsyncMetricsRecorder records on asynchronous metrics derived from metric registry.
+type AsyncMetricsRecorder interface {
+	// RecordInt64AsyncGauge records the measurement alongside labels on the int
+	// count associated with the provided handle asynchronously
+	RecordInt64AsyncGauge(handle *Int64AsyncGaugeHandle, incr int64, labels ...string)
+}
+
 // Metrics is an experimental legacy alias of the now-stable stats.MetricSet.
 // Metrics will be deleted in a future release.
 type Metrics = stats.MetricSet