From 7d93e72a6a5b7cf5552e934fff121fcdbd86c50a Mon Sep 17 00:00:00 2001
From: William Banfield <wbanfield@gmail.com>
Date: Wed, 13 Oct 2021 12:40:12 -0400
Subject: [PATCH] comments on proxy metrics

---
 internal/proxy/app_conn.go | 4 ++++
 internal/proxy/metrics.go  | 7 +++++++
 2 files changed, 11 insertions(+)

diff --git a/internal/proxy/app_conn.go b/internal/proxy/app_conn.go
index 52c5c82a0..9838eb45e 100644
--- a/internal/proxy/app_conn.go
+++ b/internal/proxy/app_conn.go
@@ -242,6 +242,10 @@ func (app *appConnSnapshot) ApplySnapshotChunkSync(
 	return app.appConn.ApplySnapshotChunkSync(ctx, req)
 }
 
+// addTimeSample returns a function that, when called, adds an observation to m.
+// The observation added to m is the number of seconds ellapsed since addTimeSample
+// was initially called. addTimeSample is meant to be called in a defer to calculate
+// the amount of time a function takes to complete.
 func addTimeSample(m metrics.Histogram) func() {
 	start := time.Now()
 	return func() { m.Observe(time.Since(start).Seconds()) }
diff --git a/internal/proxy/metrics.go b/internal/proxy/metrics.go
index ae89e8376..99bd7d7b0 100644
--- a/internal/proxy/metrics.go
+++ b/internal/proxy/metrics.go
@@ -13,10 +13,15 @@ const (
 	MetricsSubsystem = "abci_connection"
 )
 
+// Metrics contains the prometheus metrics exposed by the proxy package.
 type Metrics struct {
 	MethodTiming metrics.Histogram
 }
 
+// PrometheusMetrics constructs a Metrics instance that collects metrics samples.
+// The resulting metrics will be prefixed with namespace and labeled with the
+// defaultLabelsAndValues. defaultLabelsAndValues must be a list of string pairs
+// where the first of each pair is the label and the second is the value.
 func PrometheusMetrics(namespace string, defaultLabelsAndValues ...string) *Metrics {
 	defaultLabels := []string{}
 	for i := 0; i < len(defaultLabelsAndValues); i += 2 {
@@ -33,6 +38,8 @@ func PrometheusMetrics(namespace string, defaultLabelsAndValues ...string) *Metr
 	}
 }
 
+// NopMetrics constructs a Metrics instance that discards all samples and is suitable
+// for testing.
 func NopMetrics() *Metrics {
 	return &Metrics{
 		MethodTiming: discard.NewHistogram(),