• Dashboard (top-level) properties
• Templating (templating) properties
• Links (links) properties
• Panel group (panel_groups) properties
• Panel (panels) properties
• Axis (panels[].y_axis) properties
• Metrics (metrics) properties
• Dynamic labels
• Dashboard YAML syntax validation

Dashboard YAML properties (DEPRECATED)

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

Templating (templating) properties

Read the documentation on templating.

Links (links) properties

Read the documentation on links.

Panel group (panel_groups) properties

Dashboards display panel groups in the order they are listed in the dashboard YAML file.

In GitLab versions 13.3 and below, panel groups were ordered by a priority key, which is no longer used.

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 take the full width of their containing row.

Panel (panels) properties

Dashboards display panels in the order they are listed in the dashboard YAML file.

In GitLab versions 13.3 and below, panels were ordered by a weight key, which is no longer used.

Axis (panels[].y_axis) properties

Metrics (metrics) properties

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 are 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:

For labels to be more explicit, using variables that reflect time series labels is a good practice. The variables are 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 looks like this:

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 converting the value of label to lower-case 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 renders in the legend like this:

Dashboard YAML syntax validation

To confirm your dashboard definition contains valid YAML syntax:

1. Go to Repository > Files.
2. Go 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.

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