expose FlowMetric help and autogenerate defaults

Author: jpinsonneau

api/flowmetrics/v1alpha1/flowmetric_types.go

@@ -76,6 +76,10 @@ type FlowMetricSpec struct {
 	// +required
 	Type MetricType `json:"type"`
 
+	// Help text of the metric, as it appears in Prometheus.
+	// +optional
+	Help string `json:"help,omitempty"`
+
 	// `valueField` is the flow field that must be used as a value for this metric (for example: `Bytes`). This field must hold numeric values.
 	// Leave empty to count flows rather than a specific value per flow.
 	// Refer to the documentation for the list of available fields: https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/network_observability/json-flows-format-reference.

bundle/manifests/flows.netobserv.io_flowmetrics.yaml

@@ -192,6 +192,9 @@ spec:
                 items:
                   type: string
                 type: array
+              help:
+                description: Help text of the metric, as it appears in Prometheus.
+                type: string
               labels:
                 description: |-
                   `labels` is a list of fields that should be used as Prometheus labels, also known as dimensions (for example: `SrcK8S_Namespace`).

bundle/manifests/netobserv-operator.clusterserviceversion.yaml

@@ -253,7 +253,7 @@ metadata:
     categories: Monitoring, Networking, Observability
     console.openshift.io/plugins: '["netobserv-plugin"]'
     containerImage: quay.io/netobserv/network-observability-operator:1.9.2-community
-    createdAt: "2025-09-30T17:05:14Z"
+    createdAt: "2025-10-01T10:32:51Z"
     description: Network flows collector and monitoring solution
     operatorframework.io/initialization-resource: '{"apiVersion":"flows.netobserv.io/v1beta2",
       "kind":"FlowCollector","metadata":{"name":"cluster"},"spec": {}}'

config/crd/bases/flows.netobserv.io_flowmetrics.yaml

@@ -192,6 +192,9 @@ spec:
                 items:
                   type: string
                 type: array
+              help:
+                description: Help text of the metric, as it appears in Prometheus.
+                type: string
               labels:
                 description: |-
                   `labels` is a list of fields that should be used as Prometheus labels, also known as dimensions (for example: `SrcK8S_Namespace`).

docs/FlowMetric.md

@@ -152,6 +152,13 @@ Refer to the documentation for the list of available fields: https://docs.redhat
 For instance, when flattening `Interfaces` on a bytes counter, a flow having Interfaces [br-ex, ens5] increases one counter for `br-ex` and another for `ens5`.<br/>
         </td>
         <td>false</td>
+      </tr><tr>
+        <td><b>help</b></td>
+        <td>string</td>
+        <td>
+          Help text of the metric, as it appears in Prometheus.<br/>
+        </td>
+        <td>false</td>
       </tr><tr>
         <td><b>labels</b></td>
         <td>[]string</td>

helm/crds/flows.netobserv.io_flowmetrics.yaml

@@ -180,6 +180,9 @@ spec:
                   items:
                     type: string
                   type: array
+                help:
+                  description: Help text of the metric, as it appears in Prometheus.
+                  type: string
                 labels:
                   description: |-
                     `labels` is a list of fields that should be used as Prometheus labels, also known as dimensions (for example: `SrcK8S_Namespace`).

internal/controller/flp/flp_pipeline_builder.go

@@ -409,6 +409,7 @@ func flowMetricToFLP(fm *metricslatest.FlowMetric) (*api.MetricsItem, error) {
 	m := &api.MetricsItem{
 		Name:     metricName,
 		Type:     api.MetricEncodeOperationEnum(strings.ToLower(string(fm.Spec.Type))),
+		Help:     fm.Spec.Help,
 		Filters:  []api.MetricsFilter{},
 		Labels:   fm.Spec.Labels,
 		Remap:    remap,

internal/pkg/helper/otel/otel_config.go

@@ -89,6 +89,7 @@ func GetOtelMetrics(flpMetrics []api.MetricsItem) ([]api.MetricsItem, error) {
 		otelMetrics = append(otelMetrics, api.MetricsItem{
 			Name:       convertToOtelLabel(otelRules, m.Name),
 			Type:       m.Type,
+			Help:       m.Help,
 			Filters:    convertToOtelFilters(otelRules, m.Filters),
 			ValueKey:   convertToOtelLabel(otelRules, m.ValueKey),
 			Labels:     convertToOtelLabels(otelRules, m.Labels),

internal/pkg/metrics/predefined_metrics.go

@@ -56,6 +56,7 @@ func init() {
 					FlowMetricSpec: metricslatest.FlowMetricSpec{
 						MetricName: fmt.Sprintf("%s_%s_%s_total", groupTrimmed, lowDir, vt),
 						Type:       metricslatest.CounterMetric,
+						Help:       fmt.Sprintf("Total %s per %s in %s direction", vt, groupTrimmed, lowDir),
 						ValueField: valueField,
 						Direction:  dir,
 						Labels:     labels,
@@ -70,6 +71,7 @@ func init() {
 			FlowMetricSpec: metricslatest.FlowMetricSpec{
 				MetricName: fmt.Sprintf("%s_sampling", groupTrimmed),
 				Type:       metricslatest.GaugeMetric,
+				Help:       fmt.Sprintf("Sampling per %s", groupTrimmed),
 				ValueField: "Sampling",
 				Labels:     labels,
 			},
@@ -80,6 +82,7 @@ func init() {
 			FlowMetricSpec: metricslatest.FlowMetricSpec{
 				MetricName: fmt.Sprintf("%s_flows_total", groupTrimmed),
 				Type:       "counter",
+				Help:       fmt.Sprintf("Total flows per %s", groupTrimmed),
 				Labels:     labels,
 			},
 			tags: []string{group, group + "-flows", "flows"},
@@ -93,6 +96,7 @@ func init() {
 			FlowMetricSpec: metricslatest.FlowMetricSpec{
 				MetricName: fmt.Sprintf("%s_rtt_seconds", groupTrimmed),
 				Type:       metricslatest.HistogramMetric,
+				Help:       fmt.Sprintf("Round-trip time latency in seconds per %s", groupTrimmed),
 				ValueField: "TimeFlowRttNs",
 				Filters: []metricslatest.MetricFilter{
 					{Field: "TimeFlowRttNs", MatchType: metricslatest.MatchPresence},
@@ -115,6 +119,7 @@ func init() {
 			FlowMetricSpec: metricslatest.FlowMetricSpec{
 				MetricName: fmt.Sprintf("%s_drop_packets_total", groupTrimmed),
 				Type:       metricslatest.CounterMetric,
+				Help:       fmt.Sprintf("Total dropped packets per %s", groupTrimmed),
 				ValueField: "PktDropPackets",
 				Filters: []metricslatest.MetricFilter{
 					{Field: "PktDropPackets", MatchType: metricslatest.MatchPresence},
@@ -128,6 +133,7 @@ func init() {
 			FlowMetricSpec: metricslatest.FlowMetricSpec{
 				MetricName: fmt.Sprintf("%s_drop_bytes_total", groupTrimmed),
 				Type:       metricslatest.CounterMetric,
+				Help:       fmt.Sprintf("Total dropped bytes per %s", groupTrimmed),
 				ValueField: "PktDropBytes",
 				Filters: []metricslatest.MetricFilter{
 					{Field: "PktDropBytes", MatchType: metricslatest.MatchPresence},
@@ -148,6 +154,7 @@ func init() {
 			FlowMetricSpec: metricslatest.FlowMetricSpec{
 				MetricName: fmt.Sprintf("%s_dns_latency_seconds", groupTrimmed),
 				Type:       metricslatest.HistogramMetric,
+				Help:       fmt.Sprintf("DNS latency in seconds per %s", groupTrimmed),
 				ValueField: "DnsLatencyMs",
 				Filters: []metricslatest.MetricFilter{
 					{Field: "DnsId", MatchType: metricslatest.MatchPresence},
@@ -171,6 +178,7 @@ func init() {
 			FlowMetricSpec: metricslatest.FlowMetricSpec{
 				MetricName: fmt.Sprintf("%s_network_policy_events_total", groupTrimmed),
 				Type:       "counter",
+				Help:       fmt.Sprintf("Total network policy events per %s", groupTrimmed),
 				Labels:     netpolLabels,
 				Filters:    []metricslatest.MetricFilter{{Field: "NetworkEvents>Feature", Value: "acl"}},
 				Flatten:    []string{"NetworkEvents"},
@@ -197,6 +205,7 @@ func init() {
 			FlowMetricSpec: metricslatest.FlowMetricSpec{
 				MetricName: fmt.Sprintf("%s_ipsec_flows_total", groupTrimmed),
 				Type:       metricslatest.CounterMetric,
+				Help:       fmt.Sprintf("Total IPsec encrypted flows per %s", groupTrimmed),
 				Filters:    []metricslatest.MetricFilter{{Field: "IPSecStatus", MatchType: metricslatest.MatchPresence}},
 				Labels:     ipsecLabels,
 				Charts:     ipsecStatusChart(group),
@@ -209,6 +218,7 @@ func init() {
 		FlowMetricSpec: metricslatest.FlowMetricSpec{
 			MetricName: "node_to_node_ingress_flows_total",
 			Type:       metricslatest.CounterMetric,
+			Help:       "Total ingress flows between nodes",
 			Labels:     mapLabels[tagNodes],
 			Filters: []metricslatest.MetricFilter{
 				{Field: "FlowDirection", Value: "2", MatchType: metricslatest.MatchNotEqual},