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

@rpereira2 comment

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 the backend label returned by the Prometheus query backend:haproxy_backend_availability:ratio{env="${env}"}.
  • The query backend:haproxy_backend_availability:ratio{env="${env}"} requires the value of the env variable which means that the values for this variable need to be refreshed if the env 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.
Edited by Reuben Pereira