Spike: Select a format for defining variables in dashboard yaml files.
In order to define a variable in the dashboard we'll need to define the right format Variables allows for more interactive and dynamic dashboards. Instead of hard-coding things like server, application and pod name in the UI variables are shown as dropdown select boxes at the top of the dashboard.
What are the MVC requirements?
- Variables should be defined per dashboard
- One variable (with multiple values) per dashboard
- Applicable only for custom dashboard(?)
Open question
- Can We can have a chart without a variable, so in a single dashboard we can have multiple charts with and without variables?
- Should we support default dashboard?
This issue is the backend part in order to define the right syntax and format for the supported variables
We could start with supporting variables which get replaced by a single value. The values of the variable can be defined in the dashboard yaml file, and/or allow the user to enter any text to be used as the value of the variable.
Improvements that we can add later:
- Allow a Prometheus query to be defined whose output will be the possible values of the variable.
- Allow user to select multiple values for a variable. The multiple values will be joined using some method like csv (
value1,value2
) or pipe (value1|value2
).
Proposal
Iteration 1
The following should be added to a dashboard in order for the dashboard to have template variables. The variables can be used in queries. Later, we can add support for using variables in group/panel/chart titles.
Note that the templating
key will be a top-level dashboard property.
custom
variable type
Implementation issue: #214513 (closed)
Simple syntax for custom
variable type:
templating:
variables:
variable1: ['value1', 'value2', 'value3']
This will create a variable called variable1
, whose values can be value1
, value2
or value3
. The first value (value1
) in the array can be the default value.
Advanced syntax:
templating:
variables:
variable1: # The name that can be used in queries in the form `%{variable1}`.
label: 'Variable 1' # The label that will appear in the UI for this dropdown.
type: custom # We can add more types as we implement them.
options:
values:
- value: 'value1' # The value that will replace `${variable1}` in queries.
text: 'Var 1 Option 1' # The text that will appear in the UI dropdown.
- value: 'value2'
text: 'Var 1 Option 2'
default: true # This option should be the default value of this variable.
text
variable type
Implementation issue: #215689 (closed)
Simple syntax:
templating:
variables:
variable1: 'default value' # `text` type variable with `default value` as its default.
Advanced syntax:
templating:
variables:
variable3:
label: 'Variable 3' # The label that will appear in the UI for this dropdown.
type: text # The UI will have a free text box for this type, where the user can enter any value.
options:
default_value: 'default' # The default value for this variable.
Iteration 2:
metric_label_values
variable type
Implementation issue: #214539 (closed)
Allow values for a variable to be taken from the label values in a metric. This will be similar to the label_values(metric, label) that Grafana provides.
templating:
variables:
variable1:
label: 'Variable 1'
type: metric_label_values
options:
query: 'backend:haproxy_backend_availability:ratio{env="${env}"}'
label: 'backend'
- The option values for the above
variable1
will be all the different values for thebackend
label returned by the Prometheus querybackend:haproxy_backend_availability:ratio{env="${env}"}
. - The query
backend:haproxy_backend_availability:ratio{env="${env}"}
requires the value of theenv
variable which means that the values for this variable need to be refreshed if theenv
variable value is changed. For the MVC, we plan to refresh the entire dashboard when a variable value is changed, so this should not be a problem.