Skip to content

G
gitlab-ce
Commit 4f93e68e authored by Amy Qualls's avatar Amy Qualls Committed by Suzanne Selhorn
Browse files
Options

Create two pages for variables 

Excise variables-related information from the Prometheus page into
two pages about variables.
parent 6106c776
Hide whitespace changes
Inline Side-by-side
Showing with 188 additions and 180 deletions
doc/operations/metrics/dashboards/templating_variables.md 0 → 100644
View file @ 4f93e68e
---
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 0 → 100644
View file @ 4f93e68e
---
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
View file @ 4f93e68e
......@@ -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
View file @ 4f93e68e
......@@ -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.
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7