Improve documentation.

Signed-off-by: Cody Littley <[email protected]>
cody-littley · Nov 25, 2024 · 0217da7 · 0217da7
1 parent 02e710d
commit 0217da7
Show file tree

Hide file tree

Showing 2 changed files with 79 additions and 78 deletions.
diff --git a/common/metrics/metrics_server.go b/common/metrics/metrics_server.go
@@ -62,6 +62,9 @@ type metrics struct {
 
 	// server is the metrics server
 	server *http.Server
+
+	// quantilesMap contains a string describing the quantiles for each latency metric. Used to generate documentation.
+	quantilesMap map[metricID]string
 }
 
 // NewMetrics creates a new Metrics instance.
@@ -92,6 +95,7 @@ func NewMetrics(logger logging.Logger, config *Config) Metrics {
 		metricMap:     make(map[metricID]Metric),
 		isAlive:       atomic.Bool{},
 		server:        server,
+		quantilesMap:  make(map[metricID]string),
 	}
 	m.isAlive.Store(true)
 	return m
@@ -208,11 +212,20 @@ func (m *metrics) NewLatencyMetric(
 		return preExistingMetric.(LatencyMetric), nil
 	}
 
+	quantilesString := ""
+
 	objectives := make(map[float64]float64, len(quantiles))
-	for _, q := range quantiles {
+	for i, q := range quantiles {
 		objectives[q.Quantile] = q.Error
+
+		quantilesString += fmt.Sprintf("`%.3f`", q.Quantile)
+		if i < len(quantiles)-1 {
+			quantilesString += ", "
+		}
 	}
 
+	m.quantilesMap[id] = quantilesString
+
 	vec, ok := m.summaryVecMap[name]
 	if !ok {
 		vec = promauto.With(m.registry).NewSummaryVec(
@@ -370,12 +383,8 @@ func (m *metrics) NewAutoGauge(
 func (m *metrics) GenerateMetricsDocumentation() string {
 	sb := &strings.Builder{}
 
-	enabledCount := 0
 	metricIDs := make([]*metricID, 0, len(m.metricMap))
-	for id, metric := range m.metricMap {
-		if metric.Enabled() {
-			enabledCount++
-		}
+	for id := range m.metricMap {
 		boundID := id
 		metricIDs = append(metricIDs, &boundID)
 	}
@@ -393,11 +402,10 @@ func (m *metrics) GenerateMetricsDocumentation() string {
 	slices.SortFunc(metricIDs, sortFunc)
 
 	sb.Write([]byte(fmt.Sprintf("# Metrics Documentation for namespace '%s'\n\n", m.config.Namespace)))
-	sb.Write([]byte("This documentation is automatically generated. " +
-		"It reflects the metrics that were registered at the time that this document was generated.\n\n"))
+	sb.Write([]byte(fmt.Sprintf("This documentation was automatically generated at time `%s`\n\n",
+		time.Now().Format(time.RFC3339))))
 
-	sb.Write([]byte(fmt.Sprintf("There are %d metrics registered. Of these, %d are enabled.\n\n",
-		len(m.metricMap), enabledCount)))
+	sb.Write([]byte(fmt.Sprintf("There are a total of `%d` registered metrics.\n\n", len(m.metricMap))))
 
 	for _, id := range metricIDs {
 		metric := m.metricMap[*id]
@@ -412,21 +420,19 @@ func (m *metrics) GenerateMetricsDocumentation() string {
 		sb.Write([]byte(fmt.Sprintf("%s\n\n", metric.Description())))
 		sb.Write([]byte("|   |   |\n"))
 		sb.Write([]byte("|---|---|\n"))
-		sb.Write([]byte(fmt.Sprintf("| **Name** | %s |\n", metric.Name())))
-		sb.Write([]byte(fmt.Sprintf("| **Unit** | %s |\n", metric.Unit())))
+		sb.Write([]byte(fmt.Sprintf("| **Name** | `%s` |\n", metric.Name())))
+		sb.Write([]byte(fmt.Sprintf("| **Unit** | `%s` |\n", metric.Unit())))
 		if id.label == "" {
 			sb.Write([]byte(fmt.Sprintf("| **Label** | - |\n")))
 		} else {
-			sb.Write([]byte(fmt.Sprintf("| **Label** | %s |\n", metric.Label())))
+			sb.Write([]byte(fmt.Sprintf("| **Label** | `%s` |\n", metric.Label())))
 		}
-		sb.Write([]byte(fmt.Sprintf("| **Type** | %s |\n", metric.Type())))
-		sb.Write([]byte(fmt.Sprintf("| **Fully Qualified Name** | %s_%s_%s |\n",
-			m.config.Namespace, id.name, id.unit)))
-		enabledString := "enabled"
-		if !metric.Enabled() {
-			enabledString = "disabled"
+		sb.Write([]byte(fmt.Sprintf("| **Type** | `%s` |\n", metric.Type())))
+		if metric.Type() == "latency" {
+			sb.Write([]byte(fmt.Sprintf("| **Quantiles** | %s |\n", m.quantilesMap[*id])))
 		}
-		sb.Write([]byte(fmt.Sprintf("| **Status** | %s |\n\n", enabledString)))
+		sb.Write([]byte(fmt.Sprintf("| **Fully Qualified Name** | `%s_%s_%s` |\n",
+			m.config.Namespace, id.name, id.unit)))
 	}
 
 	return sb.String()

diff --git a/common/metrics/test/metrics.md b/common/metrics/test/metrics.md
@@ -1,104 +1,99 @@
 # Metrics Documentation for namespace 'test'
 
-This documentation is automatically generated. It reflects the metrics that were registered at the time that this document was generated.
+This documentation was automatically generated at time `2024-11-25T10:13:43-06:00`
 
-There are 7 metrics registered. Of these, 7 are enabled.
+There are a total of `7` registered metrics.
 
 ---
 
-## c1
+## c1_count
 
 this metric shows the number of times the sleep cycle has been executed
 
-| Field | Value |
+|   |   |
 |---|---|
-| **Name** | 'c1' |
-| **Label** | '' |
-| **Type** | counter |
-| **Unit** | count |
-| **Status** | enabled |
-
+| **Name** | `c1` |
+| **Unit** | `count` |
+| **Label** | - |
+| **Type** | `counter` |
+| **Fully Qualified Name** | `test_c1_count` |
 ---
 
-## c1:DOUBLE
+## c1_count: DOUBLE
 
 this metric shows the number of times the sleep cycle has been executed, doubled
 
-| Field | Value |
+|   |   |
 |---|---|
-| **Name** | 'c1' |
-| **Label** | 'DOUBLE' |
-| **Type** | counter |
-| **Unit** | count |
-| **Status** | enabled |
-
+| **Name** | `c1` |
+| **Unit** | `count` |
+| **Label** | `DOUBLE` |
+| **Type** | `counter` |
+| **Fully Qualified Name** | `test_c1_count` |
 ---
 
-## g1
+## g1_milliseconds
 
 this metric shows the duration of the most recent sleep cycle
 
-| Field | Value |
+|   |   |
 |---|---|
-| **Name** | 'g1' |
-| **Label** | '' |
-| **Type** | gauge |
-| **Unit** | milliseconds |
-| **Status** | enabled |
-
+| **Name** | `g1` |
+| **Unit** | `milliseconds` |
+| **Label** | - |
+| **Type** | `gauge` |
+| **Fully Qualified Name** | `test_g1_milliseconds` |
 ---
 
-## g1:autoPoll
+## g1_milliseconds: autoPoll
 
 this metric shows the sum of all sleep cycles
 
-| Field | Value |
+|   |   |
 |---|---|
-| **Name** | 'g1' |
-| **Label** | 'autoPoll' |
-| **Type** | gauge |
-| **Unit** | milliseconds |
-| **Status** | enabled |
-
+| **Name** | `g1` |
+| **Unit** | `milliseconds` |
+| **Label** | `autoPoll` |
+| **Type** | `gauge` |
+| **Fully Qualified Name** | `test_g1_milliseconds` |
 ---
 
-## g1:previous
+## g1_milliseconds: previous
 
 this metric shows the duration of the second most recent sleep cycle
 
-| Field | Value |
+|   |   |
 |---|---|
-| **Name** | 'g1' |
-| **Label** | 'previous' |
-| **Type** | gauge |
-| **Unit** | milliseconds |
-| **Status** | enabled |
-
+| **Name** | `g1` |
+| **Unit** | `milliseconds` |
+| **Label** | `previous` |
+| **Type** | `gauge` |
+| **Fully Qualified Name** | `test_g1_milliseconds` |
 ---
 
-## l1
+## l1_ms
 
 this metric shows the latency of the sleep cycle
 
-| Field | Value |
+|   |   |
 |---|---|
-| **Name** | 'l1' |
-| **Label** | '' |
-| **Type** | latency |
-| **Unit** | seconds |
-| **Status** | enabled |
-
+| **Name** | `l1` |
+| **Unit** | `seconds` |
+| **Label** | - |
+| **Type** | `latency` |
+| **Quantiles** | `0.500`, `0.900`, `0.990` |
+| **Fully Qualified Name** | `test_l1_ms` |
 ---
 
-## l1:HALF
+## l1_ms: HALF
 
 this metric shows the latency of the sleep cycle, divided by two
 
-| Field | Value |
+|   |   |
 |---|---|
-| **Name** | 'l1' |
-| **Label** | 'HALF' |
-| **Type** | latency |
-| **Unit** | seconds |
-| **Status** | enabled |
-
+| **Name** | `l1` |
+| **Unit** | `seconds` |
+| **Label** | `HALF` |
+| **Type** | `latency` |
+| **Quantiles** | `0.500`, `0.900`, `0.990` |
+| **Fully Qualified Name** | `test_l1_ms` |