Expose prometheus HELP information (#1107)

* expose prometheus HELP information

* add help text as description for otel exporters

Author: jpinsonneau

docs/api.md

@@ -17,6 +17,7 @@ Following is the supported API format for prometheus encode:
                     counter: monotonically increasing counter whose value can only increase
                     histogram: counts samples in configurable buckets
                     agg_histogram: counts samples in configurable buckets, pre-aggregated via an Aggregate stage
+                 help: the metric help text
                  filters: a list of criteria to filter entries by
                          key: the key to match and filter by
                          value: the value to match and filter by
@@ -457,6 +458,7 @@ Following is the supported API format for writing metrics to an OpenTelemetry co
                     counter: monotonically increasing counter whose value can only increase
                     histogram: counts samples in configurable buckets
                     agg_histogram: counts samples in configurable buckets, pre-aggregated via an Aggregate stage
+                 help: the metric help text
                  filters: a list of criteria to filter entries by
                          key: the key to match and filter by
                          value: the value to match and filter by

pkg/api/encode_prom.go

@@ -49,6 +49,7 @@ type PromConnectionInfo struct {
 type MetricsItem struct {
 	Name       string                    `yaml:"name" json:"name" doc:"the metric name"`
 	Type       MetricEncodeOperationEnum `yaml:"type" json:"type" doc:"(enum) one of the following:"`
+	Help       string                    `yaml:"help,omitempty" json:"help,omitempty" doc:"the metric help text"`
 	Filters    []MetricsFilter           `yaml:"filters" json:"filters" doc:"a list of criteria to filter entries by"`
 	ValueKey   string                    `yaml:"valueKey" json:"valueKey" doc:"entry key from which to resolve metric value"`
 	Labels     []string                  `yaml:"labels" json:"labels" doc:"labels to be associated with the metric"`

pkg/pipeline/encode/encode_prom.go

@@ -116,25 +116,25 @@ func (e *Prometheus) Cleanup(cleanupFunc interface{}) {
 }
 
 func (e *Prometheus) addCounter(fullMetricName string, mInfo *metrics.Preprocessed) prometheus.Collector {
-	counter := prometheus.NewCounterVec(prometheus.CounterOpts{Name: fullMetricName, Help: ""}, mInfo.TargetLabels())
+	counter := prometheus.NewCounterVec(prometheus.CounterOpts{Name: fullMetricName, Help: mInfo.Help}, mInfo.TargetLabels())
 	e.metricCommon.AddCounter(fullMetricName, counter, mInfo)
 	return counter
 }
 
 func (e *Prometheus) addGauge(fullMetricName string, mInfo *metrics.Preprocessed) prometheus.Collector {
-	gauge := prometheus.NewGaugeVec(prometheus.GaugeOpts{Name: fullMetricName, Help: ""}, mInfo.TargetLabels())
+	gauge := prometheus.NewGaugeVec(prometheus.GaugeOpts{Name: fullMetricName, Help: mInfo.Help}, mInfo.TargetLabels())
 	e.metricCommon.AddGauge(fullMetricName, gauge, mInfo)
 	return gauge
 }
 
 func (e *Prometheus) addHistogram(fullMetricName string, mInfo *metrics.Preprocessed) prometheus.Collector {
-	histogram := prometheus.NewHistogramVec(prometheus.HistogramOpts{Name: fullMetricName, Help: ""}, mInfo.TargetLabels())
+	histogram := prometheus.NewHistogramVec(prometheus.HistogramOpts{Name: fullMetricName, Help: mInfo.Help}, mInfo.TargetLabels())
 	e.metricCommon.AddHist(fullMetricName, histogram, mInfo)
 	return histogram
 }
 
 func (e *Prometheus) addAgghistogram(fullMetricName string, mInfo *metrics.Preprocessed) prometheus.Collector {
-	agghistogram := prometheus.NewHistogramVec(prometheus.HistogramOpts{Name: fullMetricName, Help: ""}, mInfo.TargetLabels())
+	agghistogram := prometheus.NewHistogramVec(prometheus.HistogramOpts{Name: fullMetricName, Help: mInfo.Help}, mInfo.TargetLabels())
 	e.metricCommon.AddAggHist(fullMetricName, agghistogram, mInfo)
 	return agghistogram
 }

pkg/pipeline/encode/opentelemetry/encode_otlpmetrics.go

@@ -154,7 +154,7 @@ func newEncodeOtlpMetricsWithMeter(ctx context.Context, stageName string, opMetr
 		mInfo := metrics.Preprocess(mCfg)
 		switch mCfg.Type {
 		case api.MetricCounter:
-			counter, err := meter.Float64Counter(fullMetricName)
+			counter, err := meter.Float64Counter(fullMetricName, metric.WithDescription(mCfg.Help))
 			if err != nil {
 				log.Errorf("error during counter creation: %v", err)
 				return nil, err
@@ -165,6 +165,7 @@ func newEncodeOtlpMetricsWithMeter(ctx context.Context, stageName string, opMetr
 			obs := Float64Gauge{observations: make(map[string]Float64GaugeEntry)}
 			gauge, err := meterFactory.Float64ObservableGauge(
 				fullMetricName,
+				metric.WithDescription(mCfg.Help),
 				metric.WithFloat64Callback(obs.Callback),
 			)
 			if err != nil {
@@ -176,12 +177,12 @@ func newEncodeOtlpMetricsWithMeter(ctx context.Context, stageName string, opMetr
 			var histo metric.Float64Histogram
 			var err error
 			if len(mCfg.Buckets) == 0 {
-				histo, err = meter.Float64Histogram(fullMetricName)
+				histo, err = meter.Float64Histogram(fullMetricName, metric.WithDescription(mCfg.Help))
 			} else {
 				histo, err = meter.Float64Histogram(fullMetricName,
+					metric.WithDescription(mCfg.Help),
 					metric.WithExplicitBucketBoundaries(mCfg.Buckets...),
 				)
-
 			}
 			if err != nil {
 				log.Errorf("error during histogram creation: %v", err)