Commit e7e6160b authored by Amy Qualls's avatar Amy Qualls

Merge branch 'variables-mvc-docs' into 'master'

Add documentation for templating variables

See merge request gitlab-org/gitlab!31933
parents aa13a6c9 c9c96a2e
...@@ -180,6 +180,8 @@ Multiple metrics can be displayed on the same chart if the fields **Name**, **Ty ...@@ -180,6 +180,8 @@ Multiple metrics can be displayed on the same chart if the fields **Name**, **Ty
#### Query Variables #### 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: 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` - `ci_environment_slug`
...@@ -192,6 +194,12 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.md) ...@@ -192,6 +194,12 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.md)
NOTE: **Note:** NOTE: **Note:**
Variables for Prometheus queries must be lowercase. Variables for Prometheus queries must be lowercase.
##### User-defined variables
[Variables can be defined](#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). 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 Support for the `"%{ci_environment_slug}"` format was
...@@ -303,19 +311,29 @@ If you select another branch, this branch should be merged to your **default** b ...@@ -303,19 +311,29 @@ If you select another branch, this branch should be merged to your **default** b
Dashboards have several components: Dashboards have several components:
- Templating variables.
- Panel groups, which consist of panels. - Panel groups, which consist of panels.
- Panels, which support one or more metrics. - Panels, which support one or more metrics.
The following tables outline the details of expected properties. The following tables outline the details of expected properties.
**Dashboard properties:** ##### **Dashboard (top-level) properties**
| Property | Type | Required | Description | | Property | Type | Required | Description |
| ------ | ------ | ------ | ------ | | ------ | ------ | ------ | ------ |
| `dashboard` | string | yes | Heading for the dashboard. Only one dashboard should be defined per file. | | `dashboard` | string | yes | Heading for the dashboard. Only one dashboard should be defined per file. |
| `panel_groups` | array | yes | The panel groups which should be on the dashboard. | | `panel_groups` | array | yes | The panel groups which should be on the dashboard. |
| `templating` | Hash | no | Top level key under which templating related options can be added. |
**Panel group (`panel_groups`) properties:** ##### **Templating (`templating`) properties**
| Property | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
| `variables` | Hash | no | Variables can be defined here. |
Read the documentation on [templating](#templating-variables-for-metrics-dashboards).
##### **Panel group (`panel_groups`) properties**
| Property | Type | Required | Description | | Property | Type | Required | Description |
| ------ | ------ | ------ | ------ | | ------ | ------ | ------ | ------ |
...@@ -323,7 +341,7 @@ The following tables outline the details of expected properties. ...@@ -323,7 +341,7 @@ The following tables outline the details of expected properties.
| `priority` | number | optional, defaults to order in file | Order to appear on the dashboard. Higher number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | | `priority` | number | optional, defaults to order in file | Order to appear on the dashboard. Higher number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. |
| `panels` | array | required | The panels which should be in the panel group. | | `panels` | array | required | The panels which should be in the panel group. |
**Panel (`panels`) properties:** ##### **Panel (`panels`) properties**
| Property | Type | Required | Description | | Property | Type | Required | Description |
| ------ | ------ | ------ | ------- | | ------ | ------ | ------ | ------- |
...@@ -335,7 +353,7 @@ The following tables outline the details of expected properties. ...@@ -335,7 +353,7 @@ The following tables outline the details of expected properties.
| `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. | | `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`. | | `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:** ##### **Axis (`panels[].y_axis`) properties**
| Property | Type | Required | Description | | Property | Type | Required | Description |
| ----------- | ------ | ----------------------------- | -------------------------------------------------------------------- | | ----------- | ------ | ----------------------------- | -------------------------------------------------------------------- |
...@@ -343,7 +361,7 @@ The following tables outline the details of expected properties. ...@@ -343,7 +361,7 @@ The following tables outline the details of expected properties.
| `format` | string | no, defaults to `engineering` | Unit format used. See the [full list of units](prometheus_units.md). | | `format` | string | no, defaults to `engineering` | Unit format used. See the [full list of units](prometheus_units.md). |
| `precision` | number | no, defaults to `2` | Number of decimal places to display in the number. | | | `precision` | number | no, defaults to `2` | Number of decimal places to display in the number. | |
**Metrics (`metrics`) properties:** ##### **Metrics (`metrics`) properties**
| Property | Type | Required | Description | | Property | Type | Required | Description |
| ------ | ------ | ------ | ------ | | ------ | ------ | ------ | ------ |
...@@ -652,6 +670,106 @@ Note the following properties: ...@@ -652,6 +670,106 @@ Note the following properties:
![heatmap panel type](img/heatmap_panel_type.png) ![heatmap panel type](img/heatmap_panel_type.png)
### Templating variables for metrics dashboards
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](#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.
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 `var1_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.
```
### View and edit the source file of a custom dashboard ### View and edit the source file of a custom dashboard
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34779) in GitLab 12.5. > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34779) in GitLab 12.5.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment