Dashboard YAML properties (deprecated) (FREE)

Deprecated in GitLab 14.7.

WARNING: This feature is in its end-of-life process. It is deprecated in GitLab 14.7, and is planned for removal in GitLab 16.0.

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.

Links (`links`) properties

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

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.

Property	Type	Required	Description
`group`	string	required	Heading for the panel group.
`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 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.

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
`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/number	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 is used.
`query_range`	string/number	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 is used.
`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 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

Introduced in GitLab 13.1.

To confirm your dashboard definition contains valid YAML syntax:

Go to Repository > Files.
Go to your dashboard file in your repository.
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:

dashboard: can't be blank learn more
panel_groups: should be an array of panel_groups objects learn more
group: can't be blank learn more
panels: should be an array of panels objects learn more
title: can't be blank learn more
metrics: should be an array of metrics objects learn more
query: can't be blank learn more
query_range: can't be blank learn more
unit: can't be blank learn more
YAML syntax: The parsed YAML is too big

This is displayed when the YAML file is larger than 1 MB.
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

Dashboard YAML properties (deprecated) (FREE)

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