Dashboard YAML properties (DEPRECATED)

Deprecated in GitLab 14.7.

caution
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

PropertyTypeRequiredDescription
dashboardstringyesHeading for the dashboard. Only one dashboard should be defined per file.
panel_groupsarrayyesThe panel groups which should be on the dashboard.
templatinghashnoTop level key under which templating related options can be added.
linksarraynoAdd links to display on the dashboard.

Templating (templating) properties

PropertyTypeRequiredDescription
variableshashyesVariables can be defined here.

Read the documentation on templating.

PropertyTypeRequiredDescription
urlstringyesThe address of the link.
titlestringnoDisplay title for the link.
typestringnoType 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.

PropertyTypeRequiredDescription
groupstringrequiredHeading for the panel group.
panelsarrayrequiredThe 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.

PropertyTypeRequiredDescription
typestringno, 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.
titlestringyesHeading for the panel.
y_labelstringno, but highly encouragedY-Axis label for the panel.
y_axisstringnoY-Axis configuration for the panel.
max_valuenumbernoDenominator value used for calculating percentile based results
metricsarrayyesThe 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.
linksarraynoAdd links to display on the chart’s context menu.

Axis (panels[].y_axis) properties

PropertyTypeRequiredDescription 
namestringno, but highly encouragedY-Axis label for the panel. Replaces y_label if set. 
formatstringno, defaults to engineering Unit format used. See the full list of units. 
precisionnumberno, defaults to 2 Number of decimal places to display in the number. 

Metrics (metrics) properties

PropertyTypeRequiredDescription
idstringnoUsed for associating dashboard metrics with database records. Must be unique across dashboard configuration files. Required for alerting (support not yet enabled, see relevant issue).
unitstringyesDefines the unit of the query’s return data.
labelstringno, but highly encouragedDefines the legend-label for the query. Should be unique within the panel’s metrics. Can contain time series labels as interpolated variables.
querystring/numberyes if query_range is not definedDefines the Prometheus query to be used to populate the chart/panel. If defined, the query endpoint of the Prometheus API is used.
query_rangestring/numberyes if query is not definedDefines the Prometheus query to be used to populate the chart/panel. If defined, the query_range endpoint of the Prometheus API is used.
stepnumberno, value is calculated if not definedDefines 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:

repeated legend label chart

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:

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

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