feat(doc): separate table for metrics contains prefix (#1354)

## Which problem is this PR solving?

The current metrics metadata generator does not resolve dynamically
assigned prefixes during metrics registration. As a result, metrics with
dynamic prefixes are not displayed with their full names. To improve
clarity, these metrics should be shown in a separate table.

## Short description of the changes

- Identified that certain packages in Refinery—specifically those used
for peer and incoming nodes, as well as the sampling package—assign
dynamic prefixes to their metrics.
- Added logic to the generator to detect metrics from these packages and
categorize them separately.
- Updated the metrics.tmpl template to display metrics with dynamic
prefixes in a distinct table, ensuring clear differentiation between
metrics with and without full names.

collect/collect.go

@@ -126,6 +126,8 @@ var inMemCollectorMetrics = []metrics.Metadata{
 	{Name: TraceSendLateSpan, Type: metrics.Counter, Unit: metrics.Dimensionless, Description: "number of spans that are sent due to late span arrival"},
 
 	{Name: "dropped_from_stress", Type: metrics.Counter, Unit: metrics.Dimensionless, Description: "number of traces dropped due to stress relief"},
+	{Name: "trace_kept_sample_rate", Type: metrics.Histogram, Unit: metrics.Dimensionless, Description: "sample rate of kept traces"},
+	{Name: "trace_aggregate_sample_rate", Type: metrics.Histogram, Unit: metrics.Dimensionless, Description: "aggregate sample rate of both kept and dropped traces"},
 }
 
 func (i *InMemCollector) Start() error {

config/metadata/configMeta.yaml

@@ -357,6 +357,7 @@ groups:
       - name: SpanLimit
         type: int
         valuetype: nondefault
+        firstversion: v2.8
         default: 0
         reload: true
         summary: is the number of spans after which a trace becomes eligible for a trace decision.

metrics.md

@@ -1,7 +1,12 @@
-# Metrics Documentation
-# Automatically generated on 2024-09-26 at 18:58:58 UTC
+# Honeycomb Refinery Metrics Documentation
 
-This document contains the description of various metrics used in the system.
+This document contains the description of various metrics used in Refinery.
+It was automatically generated on 2024-09-27 at 16:19:55 UTC.
+
+Note: This document does not include metrics defined in the dynsampler-go dependency, as those metrics are generated dynamically at runtime. As a result, certain metrics may be missing or incomplete in this document, but they will still be available during execution with their full names.
+
+## Complete Metrics
+This table includes metrics with fully defined names.
 
 | Name | Type | Unit | Description |
 |------|------|------|-------------|
@@ -23,15 +28,6 @@ This document contains the description of various metrics used in the system.
 | num_peers | Gauge | Dimensionless | the active number of peers in the cluster |
 | peer_hash | Gauge | Dimensionless | the hash of the current list of peers |
 | peer_messages | Counter | Dimensionless | the number of messages received by the peers service |
-| _num_dropped_by_drop_rule | Counter | Dimensionless | Number of traces dropped by the drop rule |
-| _num_dropped | Counter | Dimensionless | Number of traces dropped by configured sampler |
-| _num_kept | Counter | Dimensionless | Number of traces kept by configured sampler |
-| _sample_rate | Histogram | Dimensionless | Sample rate for traces |
-| enqueue_errors | Counter | Dimensionless | The number of errors encountered when enqueueing events |
-| response_20x | Counter | Dimensionless | The number of successful responses from Honeycomb |
-| response_errors | Counter | Dimensionless | The number of errors encountered when sending events to Honeycomb |
-| queued_items | UpDown | Dimensionless | The number of events queued for transmission to Honeycomb |
-| queue_time | Histogram | Microseconds | The time spent in the queue before being sent to Honeycomb |
 | trace_duration_ms | Histogram | Milliseconds | time taken to process a trace from arrival to send |
 | trace_span_count | Histogram | Dimensionless | number of spans in a trace |
 | collector_incoming_queue | Histogram | Dimensionless | number of spans currently in the incoming queue |
@@ -60,14 +56,33 @@ This document contains the description of various metrics used in the system.
 | trace_send_ejected_memsize | Counter | Dimensionless | number of traces that are ready for decision due to memory overrun |
 | trace_send_late_span | Counter | Dimensionless | number of spans that are sent due to late span arrival |
 | dropped_from_stress | Counter | Dimensionless | number of traces dropped due to stress relief |
+| trace_kept_sample_rate | Histogram | Dimensionless | sample rate of kept traces |
+| trace_aggregate_sample_rate | Histogram | Dimensionless | aggregate sample rate of both kept and dropped traces |
 | cluster_stress_level | Gauge | Dimensionless | The overall stress level of the cluster |
 | individual_stress_level | Gauge | Dimensionless | The stress level of the individual node |
 | stress_level | Gauge | Dimensionless | The stress level that's being used to determine whether to activate stress relief |
 | stress_relief_activated | Gauge | Dimensionless | Whether stress relief is currently activated |
-| _router_proxied | Counter | Dimensionless | the number of events proxied to another refinery |
-| _router_event | Counter | Dimensionless | the number of events received |
 | config_hash | Gauge | Dimensionless | The hash of the current configuration |
 | rule_config_hash | Gauge | Dimensionless | The hash of the current rules configuration |
+
+
+## Metrics with Prefix
+This table includes metrics with partially defined names.
+Metrics in this table don't contain their expected prefixes. This is because the auto-generator is unable to resolve dynamically created metric names during the generation process.
+
+| Name | Type | Unit | Description |
+|------|------|------|-------------|
+| _num_dropped_by_drop_rule | Counter | Dimensionless | Number of traces dropped by the drop rule |
+| _num_dropped | Counter | Dimensionless | Number of traces dropped by configured sampler |
+| _num_kept | Counter | Dimensionless | Number of traces kept by configured sampler |
+| _sample_rate | Histogram | Dimensionless | Sample rate for traces |
+| enqueue_errors | Counter | Dimensionless | The number of errors encountered when enqueueing events |
+| response_20x | Counter | Dimensionless | The number of successful responses from Honeycomb |
+| response_errors | Counter | Dimensionless | The number of errors encountered when sending events to Honeycomb |
+| queued_items | UpDown | Dimensionless | The number of events queued for transmission to Honeycomb |
+| queue_time | Histogram | Microseconds | The time spent in the queue before being sent to Honeycomb |
+| _router_proxied | Counter | Dimensionless | the number of events proxied to another refinery |
+| _router_event | Counter | Dimensionless | the number of events received |
 | queue_length | Gauge | Dimensionless | number of events waiting to be sent to destination |
 | queue_overflow | Counter | Dimensionless | number of events dropped due to queue overflow |
 | send_errors | Counter | Dimensionless | number of errors encountered while sending events to destination |

tools/convert/main.go

@@ -395,7 +395,7 @@ func GenerateMetricsDoc(w io.Writer) error {
 		return err
 	}
 
-	var metricsUsages []MetricsUsage
+	var metricsUsages MetricsOutput
 	err = yaml.Unmarshal(data, &metricsUsages)
 	if err != nil {
 		return err

tools/convert/metrics.go

@@ -20,8 +20,15 @@ type MetricsUsage struct {
 	Description string
 }
 
+type MetricsOutput struct {
+	Complete  []MetricsUsage
+	HasPrefix []MetricsUsage
+}
+
 const metricsImportPath = "github.com/honeycombio/refinery/metrics"
 
+var packagesContainsPrefix = []string{"route", "main", "sample", "transmit"}
+
 func GenerateMetricsMetadata() error {
 	output, err := os.Create("metricsMeta.yaml")
 	if err != nil {
@@ -40,7 +47,7 @@ func GenerateMetricsMetadata() error {
 		return fmt.Errorf("error loading packages: %v", err)
 	}
 
-	usages := make([]MetricsUsage, 0)
+	var usages MetricsOutput
 	// Traverse each package and file.
 	for _, pkg := range pkgs {
 		if !slices.Contains(maps.Keys(pkg.Imports), metricsImportPath) {
@@ -87,7 +94,12 @@ func GenerateMetricsMetadata() error {
 										if usage.Name == "" {
 											continue
 										}
-										usages = append(usages, usage)
+										if slices.Contains(packagesContainsPrefix, pkg.Name) {
+											fmt.Println("name", pkg.Name)
+											usages.HasPrefix = append(usages.HasPrefix, usage)
+										} else {
+											usages.Complete = append(usages.Complete, usage)
+										}
 										found = true
 									}
 								}
@@ -104,7 +116,7 @@ func GenerateMetricsMetadata() error {
 		}
 	}
 
-	if len(usages) == 0 {
+	if len(usages.Complete) == 0 && len(usages.HasPrefix) == 0 {
 		return fmt.Errorf("No metrics.Metadata declarations found in all packages")
 	}
 
@@ -129,7 +141,6 @@ func exprToString(expr ast.Expr, pkg *packages.Package) string {
 				strVal = constVal.Val().String()
 				break
 			}
-
 		}
 		strVal = v.Name
 	case *ast.BasicLit:
@@ -143,7 +154,7 @@ func exprToString(expr ast.Expr, pkg *packages.Package) string {
 	return strings.Trim(strVal, "\"")
 }
 
-func writeMetricsToYAML(metricsUsages []MetricsUsage, output *os.File) error {
+func writeMetricsToYAML(metricsUsages MetricsOutput, output *os.File) error {
 	// Create a new YAML encoder and write the metrics
 	encoder := yaml.NewEncoder(output)
 	defer encoder.Close()