Add format to common_metrics.yml file

Add `format` key to the panels is the default dashboard to format data.

Add documentation to match the new changes for users.

changelogs/unreleased/208258-update-documentation-and-common_metrics-yml-to-match-new-y_axis-pr.yml

+---
+title: Update charts documentation and common_metrics.yml to enable data formatting
+merge_request: 26048
+author:
+type: added

config/prometheus/common_metrics.yml

@@ -17,6 +17,8 @@ panel_groups:
   - title: "Latency"
     type: "area-chart"
     y_label: "Latency (ms)"
+    y_axis:
+      format: milliseconds
     weight: 1
     metrics:
     - id: response_metrics_nginx_ingress_latency_pod_average
@@ -26,6 +28,8 @@ panel_groups:
   - title: "HTTP Error Rate"
     type: "area-chart"
     y_label: "HTTP Errors (%)"
+    y_axis:
+      format: percentHundred
     weight: 1
     metrics:
     - id: response_metrics_nginx_ingress_http_error_rate
@@ -138,6 +142,8 @@ panel_groups:
   - title: "HTTP Error Rate (Errors / Sec)"
     type: "area-chart"
     y_label: "HTTP 500 Errors / Sec"
+    y_axis:
+      precision: 0
     weight: 1
     metrics:
     - id: response_metrics_nginx_http_error_rate
@@ -150,6 +156,8 @@ panel_groups:
   - title: "Memory Usage (Total)"
     type: "area-chart"
     y_label: "Total Memory Used (GB)"
+    y_axis:
+      format: "gibibytes"
     weight: 4
     metrics:
     - id: system_metrics_kubernetes_container_memory_total
@@ -168,6 +176,8 @@ panel_groups:
   - title: "Memory Usage (Pod average)"
     type: "line-chart"
     y_label: "Memory Used per Pod (MB)"
+    y_axis:
+      format: "mebibytes"
     weight: 2
     metrics:
     - id: system_metrics_kubernetes_container_memory_average
@@ -177,6 +187,8 @@ panel_groups:
   - title: "Canary: Memory Usage (Pod Average)"
     type: "line-chart"
     y_label: "Memory Used per Pod (MB)"
+    y_axis:
+      format: "mebibytes"
     weight: 2
     metrics:
     - id: system_metrics_kubernetes_container_memory_average_canary
@@ -206,6 +218,8 @@ panel_groups:
   - title: "Knative function invocations"
     type: "area-chart"
     y_label: "Invocations"
+    y_axis:
+      precision: 0
     weight: 1
     metrics:
     - id: system_metrics_knative_function_invocation_count

doc/development/prometheus_metrics.md

@@ -12,7 +12,10 @@ The requirement for adding a new metric is to make each query to have an unique
 - group: Response metrics (NGINX Ingress)
   metrics:
   - title: "Throughput"
-    y_label: "Requests / Sec"
+    y_axis:
+      name: "Requests / Sec"
+      format: "number"
+      precision: 2
     queries:
     - id: response_metrics_nginx_ingress_throughput_status_code
       query_range: 'sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) by (status_code)'

doc/user/project/integrations/prometheus.md

@@ -203,14 +203,17 @@ For example:
    panel_groups:
      - group: 'Group Title'
        panels:
-         - type: area-chart
-           title: "Chart Title"
-           y_label: "Y-Axis"
-           metrics:
-             - id: metric_of_ages
-               query_range: 'http_requests_total'
-               label: "Instance: {{instance}}, method: {{method}}"
-               unit: "count"
+       - type: area-chart
+         title: "Chart Title"
+         y_label: "Y-Axis"
+         y_axis:
+           format: number
+           precision: 0
+         metrics:
+         - id: my_metric_id
+           query_range: 'http_requests_total'
+           label: "Instance: {{instance}}, method: {{method}}"
+           unit: "count"
    ```
 
    The above sample dashboard would display a single area chart. Each file should
@@ -276,9 +279,18 @@ The following tables outline the details of expected properties.
 | `type` | enum | no, defaults to `area-chart` | Specifies the chart type to use, can be: `area-chart`, `line-chart` or `anomaly-chart`. |
 | `title` | string | yes | Heading for the panel. |
 | `y_label` | string | no, but highly encouraged | Y-Axis label for the panel. |
+| `y_axis` | string | no | Y-Axis configuration for the panel. |
 | `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. |
 | `metrics` | array | yes | The metrics which should be displayed in the panel. Any number of metrics can be displayed when `type` is `area-chart` or `line-chart`, whereas only 3 can be displayed when `type` is `anomaly-chart`. |
 
+**Axis (`panels[].y_axis`) properties:**
+
+| Property    | Type   | Required                  | Description                                                          |
+| ----------- | ------ | ------------------------- | -------------------------------------------------------------------- |
+| `name`      | string | no, but highly encouraged | Y-Axis label for the panel, it will replace `y_label` if set.        |
+| `format`    | string | no, defaults to `number`  | Unit format used. See the [full list of units](prometheus_units.md). |
+| `precision` | number | no, defaults to `2`       | Number of decimals to display in the number.                         |
+
 **Metrics (`metrics`) properties:**
 
 | Property | Type | Required | Description |
@@ -297,7 +309,7 @@ When a static label is used and a query returns multiple time series, then all t
 
 ```yaml
 metrics:
-  - id: metric_of_ages
+  - id: my_metric_id
     query_range: 'http_requests_total'
     label: "Time Series"
     unit: "count"
@@ -311,7 +323,7 @@ For labels to be more explicit, using variables that reflect time series labels
 
 ```yaml
 metrics:
-  - id: metric_of_ages
+  - id: my_metric_id
     query_range: 'http_requests_total'
     label: "Instance: {{instance}}, method: {{method}}"
     unit: "count"
@@ -325,7 +337,7 @@ There is also a shorthand value for dynamic dashboard labels that make use of on
 
 ```yaml
 metrics:
-  - id: metric_of_ages
+  - id: my_metric_id
     query_range: 'http_requests_total'
     label: "Method"
     unit: "count"
@@ -351,6 +363,9 @@ panel_groups:
       - type: area-chart # or line-chart
         title: 'Area Chart Title'
         y_label: "Y-Axis"
+        y_axis:
+          format: number
+          precision: 0
         metrics:
           - id: area_http_requests_total
             query_range: 'http_requests_total'

doc/user/project/integrations/prometheus_units.md

+# Unit formats reference
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/201999) in GitLab 12.9.
+
+You can select units to format your charts by adding `format` to your
+[axis configuration](prometheus.md#dashboard-yaml-properties).
+
+## Numbers
+
+For generic data, numbers are formatted according to the current locale.
+
+Formats: `number`
+
+**Examples:**
+
+| Data      | Displayed |
+| --------- | --------- |
+| `10`      | 1         |
+| `1000`    | 1,000     |
+| `1000000` | 1,000,000 |
+
+## Percentage
+
+For percentage data, format numbers in the chart with a `%` symbol.
+
+Formats supported: `percent`, `percentHundred`
+
+**Examples:**
+
+| Format           | Data  | Displayed |
+| ---------------- | ----- | --------- |
+| `percent`        | `0.5` | 50%       |
+| `percent`        | `1`   | 100%      |
+| `percent`        | `2`   | 200%      |
+| `percentHundred` | `50`  | 50%       |
+| `percentHundred` | `100` | 100%      |
+| `percentHundred` | `200` | 200%      |
+
+## Duration
+
+For time durations, format numbers in the chart with a time unit symbol.
+
+Formats supported: `milliseconds`, `seconds`
+
+**Examples:**
+
+| Format         | Data   | Displayed |
+| -------------- | ------ | --------- |
+| `milliseconds` | `10`   | 10ms      |
+| `milliseconds` | `500`  | 100ms     |
+| `milliseconds` | `1000` | 1000ms    |
+| `seconds`      | `10`   | 10s       |
+| `seconds`      | `500`  | 500s      |
+| `seconds`      | `1000` | 1000s     |
+
+## Digital (Metric)
+
+Converts a number of bytes using metric prefixes. It scales to
+use the unit that's the best fit.
+
+Formats supported:
+
+- `decimalBytes`
+- `kilobytes`
+- `megabytes`
+- `gigabytes`
+- `terabytes`
+- `petabytes`
+
+**Examples:**
+
+| Format         | Data      | Displayed |
+| -------------- | --------- | --------- |
+| `decimalBytes` | `1`       | 1B        |
+| `decimalBytes` | `1000`    | 1kB       |
+| `decimalBytes` | `1000000` | 1MB       |
+| `kilobytes`    | `1`       | 1kB       |
+| `kilobytes`    | `1000`    | 1MB       |
+| `kilobytes`    | `1000000` | 1GB       |
+| `megabytes`    | `1`       | 1MB       |
+| `megabytes`    | `1000`    | 1GB       |
+| `megabytes`    | `1000000` | 1TB       |
+
+## Digital (IEC)
+
+Converts a number of bytes using binary prefixes. It scales to
+use the unit that's the best fit.
+
+Formats supported:
+
+- `bytes`
+- `kibibytes`
+- `mebibytes`
+- `gibibytes`
+- `tebibytes`
+- `pebibytes`
+
+**Examples:**
+
+| Format      | Data          | Displayed |
+| ----------- | ------------- | --------- |
+| `bytes`     | `1`           | 1B        |
+| `bytes`     | `1024`        | 1KiB      |
+| `bytes`     | `1024 * 1024` | 1MiB      |
+| `kibibytes` | `1`           | 1KiB      |
+| `kibibytes` | `1024`        | 1MiB      |
+| `kibibytes` | `1024 * 1024` | 1GiB      |
+| `mebibytes` | `1`           | 1MiB      |
+| `mebibytes` | `1024`        | 1GiB      |
+| `mebibytes` | `1024 * 1024` | 1TiB      |

spec/fixtures/lib/gitlab/metrics/dashboard/schemas/axis.json

+{
+  "type": "object",
+  "required": [],
+  "properties": {
+    "name": { "type": "string" },
+    "precision": { "type": "number" },
+    "format": { "type": "string" }
+  },
+  "additionalProperties": false
+}

spec/fixtures/lib/gitlab/metrics/dashboard/schemas/panels.json

@@ -9,6 +9,7 @@
     "title": { "type": "string" },
     "type": { "type": "string" },
     "y_label": { "type": "string" },
+    "y_axis": { "$ref": "axis.json" },
     "weight": { "type": "number" },
     "metrics": {
       "type": "array",