Apply a Dashboard Scope to a PromQL Query

Step by step guide to apply a dashboard scope to a PromQL Query in Dashboards

The dashboard scope is automatically applied only to form-based panels. To scope a panel built from a PromQL query, you must use a scope variable within the query. The variable will take the value of the referenced scope parameter, and the PromQL panel will change accordingly.

The easiest way to apply the full dashboard scope to a PromQL query is to use $__scope.


The following example show how to use scope variables within PromQL queries when a finer control is required (for example when you want to apply a scope entry on specific metrics).

Example: CPU Used Percent

The following query returns the CPU used percent for all the hosts, regardless of the scope configured at the dashboard level, with a mobile average depending on the time span defined.


To scope this query, you must set up an appropriate scope variable. A key step is to provide a variable name that is referenced as part of the query.

In this example, hostname is used as the variable name. The host can then be referenced using $hostname as follows:


Depending on the operator specified while configuring scope values, you might need to use a different operator within the query. If you are not using the correct operator for the scope type, the system will perform the query but will show a warning as the results may not be the expected ones.

Scope OperatorPromQL Filter OperatorExample
  • is foo
  • is not foo
  • = : Select labels that are exactly equal to the provided string.
  • != : Select labels that are not equal to the provided string.
  • in foo,bar
  • not in foo,bar
  • =~: Select labels that regex-match the provided string.
  • !~ : Select labels that do not regex-match the provided string.