Document API, gen bundle, fix tests, update examples

netobserv · Apr 4, 2024 · a40f093 · a40f093
1 parent 62a40b4
commit a40f093
Show file tree

Hide file tree

Showing 25 changed files with 617 additions and 141 deletions.
diff --git a/apis/flowmetrics/v1alpha1/flowmetric_types.go b/apis/flowmetrics/v1alpha1/flowmetric_types.go
@@ -45,7 +45,7 @@ type MetricFilter struct {
 	// +required
 	Field string `json:"field"`
 
-	// Value to filter on
+	// Value to filter on. When `matchType` is `Equal` or `NotEqual`, you can use field injection with `$(SomeField)` to refer to any other field of the flow.
 	// +optional
 	Value string `json:"value"`
 
@@ -112,7 +112,7 @@ type FlowMetricSpec struct {
 
 	// When non-zero, scale factor (divider) of the value. Metric value = Flow value / Divider.
 	// +optional
-	Divider float64 `json:"divider"`
+	Divider string `json:"divider"`
 
 	// Charts configuration
 	// +optional
@@ -127,24 +127,56 @@ const (
 	UnitSeconds         Unit      = "seconds"
 	UnitBPS             Unit      = "Bps"
 	UnitPPS             Unit      = "pps"
+	UnitPercent         Unit      = "percent"
 	ChartTypeSingleStat ChartType = "SingleStat"
 	ChartTypeLine       ChartType = "Line"
 	ChartTypeStackArea  ChartType = "StackArea"
 )
 
 // Configures charts / dashboard generation associated to a metric
 type Chart struct {
-	DashboardName string    `json:"dashboardName"`
-	SectionName   string    `json:"sectionName"`
-	Title         string    `json:"title"`
-	Unit          Unit      `json:"unit"`
-	Type          ChartType `json:"type"`
-	Queries       []Query   `json:"queries"`
+	// Name of the containing dashboard. If this name does not refer to an existing dashboard, a new dashboard is created.
+	// +kubebuilder:default:="NetObserv"
+	DashboardName string `json:"dashboardName"`
+
+	// Name of the containing dashboard section. If this name does not refer to an existing section, a new section is created.
+	// If `sectionName` is omitted or empty, the chart is placed in the global top section.
+	// +optional
+	SectionName string `json:"sectionName"`
+
+	// Title of the chart.
+	// +required
+	Title string `json:"title"`
+
+	// Unit of this chart. Only a few units are currently supported. Leave empty to use generic number.
+	// +kubebuilder:validation:Enum:="bytes";"seconds";"Bps";"pps";"percent"
+	// +optional
+	Unit Unit `json:"unit"`
+
+	// Type of the chart.
+	// +kubebuilder:validation:Enum:="SingleStat";"Line";"StackArea"
+	// +required
+	Type ChartType `json:"type"`
+
+	// List of queries to be displayed on this chart. If `type` is `SingleStat` and multiple queries are provided,
+	// this chart will be automatically expanded in several panels (one per query).
+	// +required
+	Queries []Query `json:"queries"`
 }
 
 // Configures PromQL queries
 type Query struct {
+	// The `promQL` query to be run against Prometheus. If the chart `type` is `SingleStat`, this query should only return
+	// a single timeseries. For other types, a top 7 is displayed.
+	// You can use `$METRIC` to refer to the metric defined in this resource. For example: `sum(rate($METRIC[2m]))`.
+	// To learn more about `promQL`, refer to the Prometheus documentation: https://prometheus.io/docs/prometheus/latest/querying/basics/
+	// +required
 	PromQL string `json:"promQL"`
+
+	// The query legend that applies to each timeseries represented in this chart. When multiple timeseries are displayed, you should set a legend
+	// that distinguishes each of them. It can be done with the following format: `{{ Label }}`. For example, if the `promQL` groups timeseries per
+	// label such as: `sum(rate($METRIC[2m])) by (Label1, Label2)`, you may write as the legend: `Label1={{ Label1 }}, Label2={{ Label2 }}`.
+	// +required
 	Legend string `json:"legend"`
 }
 

diff --git a/apis/flowmetrics/v1alpha1/zz_generated.deepcopy.go b/apis/flowmetrics/v1alpha1/zz_generated.deepcopy.go
diff --git a/bundle/manifests/flows.netobserv.io_flowmetrics.yaml b/bundle/manifests/flows.netobserv.io_flowmetrics.yaml
@@ -47,6 +47,83 @@ spec:
                 items:
                   type: string
                 type: array
+              charts:
+                description: Charts configuration
+                items:
+                  description: Configures charts / dashboard generation associated
+                    to a metric
+                  properties:
+                    dashboardName:
+                      default: NetObserv
+                      description: Name of the containing dashboard. If this name
+                        does not refer to an existing dashboard, a new dashboard is
+                        created.
+                      type: string
+                    queries:
+                      description: List of queries to be displayed on this chart.
+                        If `type` is `SingleStat` and multiple queries are provided,
+                        this chart will be automatically expanded in several panels
+                        (one per query).
+                      items:
+                        description: Configures PromQL queries
+                        properties:
+                          legend:
+                            description: 'The query legend that applies to each timeseries
+                              represented in this chart. When multiple timeseries
+                              are displayed, you should set a legend that distinguishes
+                              each of them. It can be done with the following format:
+                              `{{ Label }}`. For example, if the `promQL` groups timeseries
+                              per label such as: `sum(rate($METRIC[2m])) by (Label1,
+                              Label2)`, you may write as the legend: `Label1={{ Label1
+                              }}, Label2={{ Label2 }}`.'
+                            type: string
+                          promQL:
+                            description: 'The `promQL` query to be run against Prometheus.
+                              If the chart `type` is `SingleStat`, this query should
+                              only return a single timeseries. For other types, a
+                              top 7 is displayed. You can use `$METRIC` to refer to
+                              the metric defined in this resource. For example: `sum(rate($METRIC[2m]))`.
+                              To learn more about `promQL`, refer to the Prometheus
+                              documentation: https://prometheus.io/docs/prometheus/latest/querying/basics/'
+                            type: string
+                        required:
+                        - legend
+                        - promQL
+                        type: object
+                      type: array
+                    sectionName:
+                      description: Name of the containing dashboard section. If this
+                        name does not refer to an existing section, a new section
+                        is created. If `sectionName` is omitted or empty, the chart
+                        is placed in the global top section.
+                      type: string
+                    title:
+                      description: Title of the chart.
+                      type: string
+                    type:
+                      description: Type of the chart.
+                      enum:
+                      - SingleStat
+                      - Line
+                      - StackArea
+                      type: string
+                    unit:
+                      description: Unit of this chart. Only a few units are currently
+                        supported. Leave empty to use generic number.
+                      enum:
+                      - bytes
+                      - seconds
+                      - Bps
+                      - pps
+                      - percent
+                      type: string
+                  required:
+                  - dashboardName
+                  - queries
+                  - title
+                  - type
+                  type: object
+                type: array
               direction:
                 default: Any
                 description: 'Filter for ingress, egress or any direction flows. When
@@ -58,6 +135,10 @@ spec:
                 - Egress
                 - Ingress
                 type: string
+              divider:
+                description: When non-zero, scale factor (divider) of the value. Metric
+                  value = Flow value / Divider.
+                type: string
               filters:
                 description: '`filters` is a list of fields and values used to restrict
                   which flows are taken into account. Oftentimes, these filters must
@@ -81,7 +162,9 @@ spec:
                       - NotMatchRegex
                       type: string
                     value:
-                      description: Value to filter on
+                      description: Value to filter on. When `matchType` is `Equal`
+                        or `NotEqual`, you can use field injection with `$(SomeField)`
+                        to refer to any other field of the flow.
                       type: string
                   required:
                   - field

diff --git a/bundle/manifests/netobserv-operator.clusterserviceversion.yaml b/bundle/manifests/netobserv-operator.clusterserviceversion.yaml
@@ -18,28 +18,49 @@ metadata:
             "name": "flowmetric-sample"
           },
           "spec": {
-            "filters": [
+            "charts": [
               {
-                "field": "DstPort",
-                "matchType": "Regex",
-                "value": "^\\d\\d?\\d?\\d?$"
+                "dashboardName": "NetObserv",
+                "queries": [
+                  {
+                    "legend": "",
+                    "promQL": "sum(rate($METRIC[2m]))"
+                  }
+                ],
+                "title": "Cluster ingress traffic",
+                "type": "SingleStat",
+                "unit": "Bps"
               },
               {
-                "field": "Duplicate",
-                "matchType": "NotEqual",
-                "value": "true"
-              },
+                "dashboardName": "NetObserv",
+                "queries": [
+                  {
+                    "legend": "{{DstK8S_Namespace}} / {{DstK8S_OwnerName}}",
+                    "promQL": "sum(rate($METRIC{DstK8S_Namespace!=\"\"}[2m])) by (DstK8S_Namespace, DstK8S_OwnerName)"
+                  }
+                ],
+                "sectionName": "Cluster",
+                "title": "Top cluster ingress traffic per workload",
+                "type": "StackArea",
+                "unit": "Bps"
+              }
+            ],
+            "direction": "Ingress",
+            "filters": [
               {
-                "field": "FlowDirection",
-                "matchType": "Regex",
-                "value": "1|2"
+                "field": "SrcSubnetLabel",
+                "matchType": "Absence"
               }
             ],
             "labels": [
-              "DstPort"
+              "DstK8S_HostName",
+              "DstK8S_Namespace",
+              "DstK8S_OwnerName",
+              "DstK8S_OwnerType"
             ],
-            "metricName": "service_ports_total",
-            "type": "Counter"
+            "metricName": "cluster_ingress_bytes_total",
+            "type": "Counter",
+            "valueField": "Bytes"
           }
         },
         {