Merge branch 'docs-aqualls-move-templating-variables' into 'master'

Move variables info to new pages

See merge request gitlab-org/gitlab!36630

doc/operations/metrics/dashboards/templating_variables.md

+---
+stage: Monitor
+group: APM
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# Templating variables for metrics dashboards
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214539) in GitLab 13.0.
+
+Templating variables can be used to make your metrics dashboard more versatile.
+
+`templating` is a top-level key in the
+[dashboard YAML](yaml.md#dashboard-top-level-properties).
+Define your variables in the `variables` key, under `templating`. The value of
+the `variables` key should be a hash, and each key under `variables`
+defines a templating variable on the dashboard, and may contain alphanumeric and underscore characters.
+
+A variable can be used in a Prometheus query in the same dashboard using the syntax
+described [in Using Variables](variables.md).
+
+## `text` variable type
+
+CAUTION: **Warning:**
+This variable type is an _alpha_ feature, and is subject to change at any time
+without prior notice!
+
+For each `text` variable defined in the dashboard YAML, there will be a free text
+box on the dashboard UI, allowing you to enter a value for each variable.
+
+The `text` variable type supports a simple and a full syntax.
+
+### Simple syntax
+
+This example creates a variable called `variable1`, with a default value
+of `default value`:
+
+```yaml
+templating:
+  variables:
+    variable1: 'default value'     # `text` type variable with `default value` as its default.
+```
+
+### Full syntax
+
+This example creates a variable called `variable1`, with a default value of `default`.
+The label for the text box on the UI will be the value of the `label` key:
+
+```yaml
+templating:
+  variables:
+    variable1:                       # The variable name that can be used in queries.
+      label: 'Variable 1'            # (Optional) label that will appear in the UI for this text box.
+      type: text
+      options:
+        default_value: 'default'     # (Optional) default value.
+```
+
+## `custom` variable type
+
+CAUTION: **Warning:**
+This variable type is an _alpha_ feature, and is subject to change at any time
+without prior notice!
+
+Each `custom` variable defined in the dashboard YAML creates a dropdown
+selector on the dashboard UI, allowing you to select a value for each variable.
+
+The `custom` variable type supports a simple and a full syntax.
+
+### Simple syntax
+
+This example creates a variable called `variable1`, with a default value of `value1`.
+The dashboard UI will display a dropdown with `value1`, `value2` and `value3`
+as the choices.
+
+```yaml
+templating:
+  variables:
+    variable1: ['value1', 'value2', 'value3']
+```
+
+### Full syntax
+
+This example creates a variable called `variable1`, with a default value of `value_option_2`.
+The label for the text box on the UI will be the value of the `label` key.
+The dashboard UI will display a dropdown with `Option 1` and `Option 2`
+as the choices.
+
+If you select `Option 1` from the dropdown, the variable will be replaced with `value option 1`.
+Similarly, if you select `Option 2`, the variable will be replaced with `value_option_2`:
+
+```yaml
+templating:
+  variables:
+    variable1:                           # The variable name that can be used in queries.
+      label: 'Variable 1'                # (Optional) label that will appear in the UI for this dropdown.
+      type: custom
+      options:
+        values:
+          - value: 'value option 1'        # The value that will replace the variable in queries.
+            text: 'Option 1'               # (Optional) Text that will appear in the UI dropdown.
+          - value: 'value_option_2'
+            text: 'Option 2'
+            default: true                  # (Optional) This option should be the default value of this variable.
+```
+
+## `metric_label_values` variable type
+
+CAUTION: **Warning:**
+This variable type is an _alpha_ feature, and is subject to change at any time
+without prior notice!
+
+### Full syntax
+
+This example creates a variable called `variable2`. The values of the dropdown will
+be all the different values of the `backend` label in the Prometheus series described by
+`up{env="production"}`.
+
+```yaml
+templating:
+  variables:
+    variable2:                           # The variable name that can be interpolated in queries.
+      label: 'Variable 2'                # (Optional) label that will appear in the UI for this dropdown.
+      type: metric_label_values
+      options:
+        series_selector: 'up{env="production"}'
+        label: 'backend'
+```

doc/operations/metrics/dashboards/variables.md

+---
+stage: Monitor
+group: APM
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+---
+
+# Using Variables
+
+## Query Variables
+
+Variables can be specified using double curly braces, such as `"{{ci_environment_slug}}"` ([added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20793) in GitLab 12.7).
+
+Support for the `"%{ci_environment_slug}"` format was
+[removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31581) in GitLab 13.0.
+Queries that continue to use the old format will show no data.
+
+## Predefined variables
+
+GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) in the Prometheus query. This is particularly useful for identifying a specific environment, for example with `ci_environment_slug`. The supported variables are:
+
+- `ci_environment_slug`
+- `kube_namespace`
+- `ci_project_name`
+- `ci_project_namespace`
+- `ci_project_path`
+- `ci_environment_name`
+- `__range`
+
+NOTE: **Note:**
+Variables for Prometheus queries must be lowercase.
+
+### __range
+
+The `__range` variable is useful in Prometheus
+[range vector selectors](https://prometheus.io/docs/prometheus/latest/querying/basics/#range-vector-selectors).
+Its value is the total number of seconds in the dashboard's time range.
+For example, if the dashboard time range is set to 8 hours, the value of
+`__range` is `28800s`.
+
+## User-defined variables
+
+[Variables can be defined](../../../operations/metrics/dashboards/yaml.md#templating-templating-properties) in a custom dashboard YAML file.
+
+## Query Variables from URL
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214500) in GitLab 13.0.
+
+GitLab supports setting custom variables through URL parameters. Surround the variable
+name with double curly braces (`{{example}}`) to interpolate the variable in a query:
+
+```plaintext
+avg(sum(container_memory_usage_bytes{container_name!="{{pod}}"}) by (job)) without (job)  /1024/1024/1024'
+```
+
+The URL for this query would be:
+
+```plaintext
+http://gitlab.com/<user>/<project>/-/environments/<environment_id>/metrics?dashboard=.gitlab%2Fdashboards%2Fcustom.yml&pod=POD
+```

doc/operations/metrics/dashboards/yaml.md

@@ -29,7 +29,7 @@ The following tables outline the details of expected properties.
 | -------- | ---- | -------- | ----------- |
 | `variables` | hash | yes | Variables can be defined here. |
 
-Read the documentation on [templating](../../../user/project/integrations/prometheus.md#templating-variables-for-metrics-dashboards).
+Read the documentation on [templating](templating_variables.md).
 
 ## **Links (`links`) properties**
 

doc/user/project/integrations/prometheus.md

@@ -168,60 +168,6 @@ A few fields are required:
 
 Multiple metrics can be displayed on the same chart if the fields **Name**, **Type**, and **Y-axis label** match between metrics. For example, a metric with **Name** `Requests Rate`, **Type** `Business`, and **Y-axis label** `rec / sec` would display on the same chart as a second metric with the same values. A **Legend label** is suggested if this feature is used.
 
-#### Query Variables
-
-##### Predefined variables
-
-GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) in the Prometheus query. This is particularly useful for identifying a specific environment, for example with `ci_environment_slug`. The supported variables are:
-
-- `ci_environment_slug`
-- `kube_namespace`
-- `ci_project_name`
-- `ci_project_namespace`
-- `ci_project_path`
-- `ci_environment_name`
-- `__range`
-
-NOTE: **Note:**
-Variables for Prometheus queries must be lowercase.
-
-###### __range
-
-The `__range` variable is useful in Prometheus
-[range vector selectors](https://prometheus.io/docs/prometheus/latest/querying/basics/#range-vector-selectors).
-Its value is the total number of seconds in the dashboard's time range.
-For example, if the dashboard time range is set to 8 hours, the value of
-`__range` is `28800s`.
-
-##### User-defined variables
-
-[Variables can be defined](../../../operations/metrics/dashboards/yaml.md#templating-templating-properties) in a custom dashboard YAML file.
-
-##### Using variables
-
-Variables can be specified using double curly braces, such as `"{{ci_environment_slug}}"` ([added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20793) in GitLab 12.7).
-
-Support for the `"%{ci_environment_slug}"` format was
-[removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31581) in GitLab 13.0.
-Queries that continue to use the old format will show no data.
-
-#### Query Variables from URL
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214500) in GitLab 13.0.
-
-GitLab supports setting custom variables through URL parameters. Surround the variable
-name with double curly braces (`{{example}}`) to interpolate the variable in a query:
-
-```plaintext
-avg(sum(container_memory_usage_bytes{container_name!="{{pod}}"}) by (job)) without (job)  /1024/1024/1024'
-```
-
-The URL for this query would be:
-
-```plaintext
-http://gitlab.com/<user>/<project>/-/environments/<environment_id>/metrics?dashboard=.gitlab%2Fdashboards%2Fcustom.yml&pod=POD
-```
-
 #### Editing additional metrics from the dashboard
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208976) in GitLab 12.9.
@@ -353,131 +299,6 @@ When **Metrics Dashboard YAML definition is invalid** at least one of the follow
 
 Metrics Dashboard YAML definition validation information is also available as a [GraphQL API field](../../../api/graphql/reference/index.md#metricsdashboard)
 
-### Templating variables for metrics dashboards
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214539) in GitLab 13.0.
-
-Templating variables can be used to make your metrics dashboard more versatile.
-
-#### Templating variable types
-
-`templating` is a top-level key in the
-[dashboard YAML](../../../operations/metrics/dashboards/yaml.md#dashboard-top-level-properties).
-Define your variables in the `variables` key, under `templating`. The value of
-the `variables` key should be a hash, and each key under `variables`
-defines a templating variable on the dashboard, and may contain alphanumeric and underscore characters.
-
-A variable can be used in a Prometheus query in the same dashboard using the syntax
-described [here](#using-variables).
-
-##### `text` variable type
-
-CAUTION: **Warning:**
-This variable type is an _alpha_ feature, and is subject to change at any time
-without prior notice!
-
-For each `text` variable defined in the dashboard YAML, there will be a free text
-box on the dashboard UI, allowing you to enter a value for each variable.
-
-The `text` variable type supports a simple and a full syntax.
-
-###### Simple syntax
-
-This example creates a variable called `variable1`, with a default value
-of `default value`:
-
-```yaml
-templating:
-  variables:
-    variable1: 'default value'     # `text` type variable with `default value` as its default.
-```
-
-###### Full syntax
-
-This example creates a variable called `variable1`, with a default value of `default`.
-The label for the text box on the UI will be the value of the `label` key:
-
-```yaml
-templating:
-  variables:
-    variable1:                       # The variable name that can be used in queries.
-      label: 'Variable 1'            # (Optional) label that will appear in the UI for this text box.
-      type: text
-      options:
-        default_value: 'default'     # (Optional) default value.
-```
-
-##### `custom` variable type
-
-CAUTION: **Warning:**
-This variable type is an _alpha_ feature, and is subject to change at any time
-without prior notice!
-
-Each `custom` variable defined in the dashboard YAML creates a dropdown
-selector on the dashboard UI, allowing you to select a value for each variable.
-
-The `custom` variable type supports a simple and a full syntax.
-
-###### Simple syntax
-
-This example creates a variable called `variable1`, with a default value of `value1`.
-The dashboard UI will display a dropdown with `value1`, `value2` and `value3`
-as the choices.
-
-```yaml
-templating:
-  variables:
-    variable1: ['value1', 'value2', 'value3']
-```
-
-###### Full syntax
-
-This example creates a variable called `variable1`, with a default value of `value_option_2`.
-The label for the text box on the UI will be the value of the `label` key.
-The dashboard UI will display a dropdown with `Option 1` and `Option 2`
-as the choices.
-
-If you select `Option 1` from the dropdown, the variable will be replaced with `value option 1`.
-Similarly, if you select `Option 2`, the variable will be replaced with `value_option_2`:
-
-```yaml
-templating:
-  variables:
-    variable1:                           # The variable name that can be used in queries.
-      label: 'Variable 1'                # (Optional) label that will appear in the UI for this dropdown.
-      type: custom
-      options:
-        values:
-          - value: 'value option 1'        # The value that will replace the variable in queries.
-            text: 'Option 1'               # (Optional) Text that will appear in the UI dropdown.
-          - value: 'value_option_2'
-            text: 'Option 2'
-            default: true                  # (Optional) This option should be the default value of this variable.
-```
-
-##### `metric_label_values` variable type
-
-CAUTION: **Warning:**
-This variable type is an _alpha_ feature, and is subject to change at any time
-without prior notice!
-
-###### Full syntax
-
-This example creates a variable called `variable2`. The values of the dropdown will
-be all the different values of the `backend` label in the Prometheus series described by
-`up{env="production"}`.
-
-```yaml
-templating:
-  variables:
-    variable2:                           # The variable name that can be interpolated in queries.
-      label: 'Variable 2'                # (Optional) label that will appear in the UI for this dropdown.
-      type: metric_label_values
-      options:
-        series_selector: 'up{env="production"}'
-        label: 'backend'
-```
-
 ### Add related links to custom dashboards
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216385) in GitLab 13.1.