How to add a Prometheus label variable to a Grafana dashboard

Adding a Prometheus label variable to a Grafana dashboard creates a dropdown from live label values instead of a fixed list. It is useful when one dashboard should switch between scraped targets, jobs, environments, or other Prometheus labels without editing each panel query.

A Query variable asks the selected Prometheus data source for values and stores the result with the dashboard. Using the Prometheus instance label with the Grafana variable name target_instance lets the panel query filter one scraped target at a time.

The dashboard needs an existing Prometheus data source and at least one panel query that can be filtered by the same label. The variable preview should show the expected label values, and changing the dashboard dropdown should refresh the panel with the selected label value.

Related: How to add a Prometheus data source in Grafana
Related: How to add a variable to a Grafana dashboard
Related: How to create a time series panel in Grafana

Steps to add a Prometheus label variable in Grafana:

  1. Open the dashboard that should receive the Prometheus label dropdown.
  2. Click Edit in the dashboard toolbar.
  3. Click Add variable from the dashboard editor.
  4. Select Query as the variable type.

    Query variables fetch values from a data source. Use Custom only when the allowed values are a fixed list.

  5. Enter the variable name and dashboard label.

    Use target_instance for Name and Instance for Label. The name is used inside PromQL; the label is the text shown beside the dashboard dropdown.

  6. Open the variable editor.
  7. Select the Prometheus data source.
  8. Set Query type to Label values.
  9. Set Label to the Prometheus label that should populate the dropdown.

    Use instance for a target-level dropdown. Use job, env, or another label only when that label exists on the metric series the panel should filter.

  10. Set Sort to Alphabetical (asc).
  11. Set Refresh to On dashboard load.
  12. Click Preview and confirm the expected label values appear.

    Use On time range change instead when the variable query should only show label values that exist inside the selected dashboard time range.

  13. Close the variable editor.
  14. Save the dashboard.
  15. Edit the panel that should use the variable.
  16. Add the variable to the PromQL label matcher. 
    up{instance="$target_instance"}

    Replace up and instance with the metric and label used by the dashboard panel. The variable name stays inside the matcher value as $target_instance.

  17. Save the panel.
  18. Save the dashboard.
  19. Select a different value from the Instance dropdown.
  20. Confirm the panel refreshes with only the selected Prometheus label value.

    If the panel shows No data, check the dashboard time range, the selected label value, and the panel request in Query inspector.
    Related: How to use Grafana query inspector