Dashboard YAML properties

Dashboards have several components:

  • Templating variables.
  • Panel groups, which consist of panels.
  • Panels, which support one or more metrics.

The following tables outline the details of expected properties.

Dashboard (top-level) properties

Property Type Required Description
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.
templating hash no Top level key under which templating related options can be added.
links array no Add links to display on the dashboard.

Templating (templating) properties

Property Type Required Description
variables hash yes Variables can be defined here.

Read the documentation on templating.

Property Type Required Description
url string yes The address of the link.
title string no Display title for the link.
type string no Type of the link. Specifies the link type, can be: grafana

Read the documentation on links.

Panel group (panel_groups) properties

Property Type Required Description
group string required Heading for the panel group.
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 in a panel group are laid out in rows consisting of two panels per row. An exception to this rule are single panels on a row: these panels will take the full width of their containing row.

Panel (panels) properties

Property Type Required Description
type string no, defaults to area-chart Specifies the panel type to use, for example area-chart, line-chart or anomaly-chart. Only types listed among all panel types are allowed.
title string yes Heading for the panel.
y_label string no, but highly encouraged Y-Axis label for the panel.
y_axis string no Y-Axis configuration for the panel.
max_value number no Denominator value used for calculating percentile based results
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.
links array no Add links to display on the chart’s context menu.

Axis (panels[].y_axis) properties

Property Type Required Description  
name string no, but highly encouraged Y-Axis label for the panel. Replaces y_label if set.  
format string no, defaults to engineering Unit format used. See the full list of units.  
precision number no, defaults to 2 Number of decimal places to display in the number.  

Metrics (metrics) properties

Property Type Required Description
id string no Used for associating dashboard metrics with database records. Must be unique across dashboard configuration files. Required for alerting (support not yet enabled, see relevant issue).
unit string yes Defines the unit of the query’s return data.
label string no, but highly encouraged Defines the legend-label for the query. Should be unique within the panel’s metrics. Can contain time series labels as interpolated variables.
query string yes if query_range is not defined Defines the Prometheus query to be used to populate the chart/panel. If defined, the query endpoint of the Prometheus API will be utilized.
query_range string yes if query is not defined Defines the Prometheus query to be used to populate the chart/panel. If defined, the query_range endpoint of the Prometheus API will be utilized.
step number no, value is calculated if not defined Defines query resolution step width in float number of seconds. Metrics on the same panel should use the same step value.

Dynamic labels

Dynamic labels are useful when multiple time series are returned from a Prometheus query.

When a static label is used and a query returns multiple time series, then all the legend items will be labeled the same, which makes identifying each time series difficult:

metrics:
  - id: my_metric_id
    query_range: 'http_requests_total'
    label: "Time Series"
    unit: "count"

This may render a legend like this:

repeated legend label chart

For labels to be more explicit, using variables that reflect time series labels is a good practice. The variables will be replaced by the values of the time series labels when the legend is rendered:

metrics:
  - id: my_metric_id
    query_range: 'http_requests_total'
    label: "Instance: {{instance}}, method: {{method}}"
    unit: "count"

The resulting rendered legend will look like this:

legend with label variables

There is also a shorthand value for dynamic dashboard labels that make use of only one time series label:

metrics:
  - id: my_metric_id
    query_range: 'http_requests_total'
    label: "Method"
    unit: "count"

This works by lowercasing the value of label and, if there are more words separated by spaces, replacing those spaces with an underscore (_). The transformed value is then checked against the labels of the time series returned by the Prometheus query. If a time series label is found that is equal to the transformed value, then the label value will be used and rendered in the legend like this:

legend with label shorthand variable

Dashboard YAML syntax validation

Introduced in GitLab 13.1.

To confirm your dashboard definition contains valid YAML syntax:

  1. Navigate to Repository > Files.
  2. Navigate to your dashboard file in your repository.
  3. Review the information pane about the file, displayed above the file contents.

Files with valid syntax display Metrics Dashboard YAML definition is valid, and files with invalid syntax display Metrics Dashboard YAML definition is invalid.

Metrics Dashboard_YAML_syntax_validation

When Metrics Dashboard YAML definition is invalid at least one of the following messages is displayed:

  1. dashboard: can't be blank learn more
  2. panel_groups: should be an array of panel_groups objects learn more
  3. group: can't be blank learn more
  4. panels: should be an array of panels objects learn more
  5. title: can't be blank learn more
  6. metrics: should be an array of metrics objects learn more
  7. query: can't be blank learn more
  8. query_range: can't be blank learn more
  9. unit: can't be blank learn more
  10. YAML syntax: The parsed YAML is too big

    This is displayed when the YAML file is larger than 1 MB.

  11. YAML syntax: Invalid configuration format

    This is displayed when the YAML file is empty or does not contain valid YAML.

Metrics Dashboard YAML definition validation information is also available as a GraphQL API field