#132621·grafana

Support tab-scoped (section) annotations in the v2beta1 dashboard schema

Author: Orenico10Created Sep 15, 2026Updated Sep 28, 2026
Labelstype/feature-requestautomated-triagearea/dashboard/annotationsarea/dashboard/variable

Why is this needed:

The v2beta1 dashboard schema (dashboardSectionVariables feature toggle) lets a TabsLayout tab declare its own local variables, scoped so they're invisible outside that tab. But annotations (spec.annotations[]) can only be defined dashboard-wide - DashboardTabsLayoutTabSpec has no annotations field.

This creates a silent failure mode: if an annotation's query filters on a tab-scoped variable, the variable is unresolved at the dashboard-global annotation's evaluation point, so the annotation never renders anywhere, on any panel. There's no error. The underlying metric query can be verified as correct in Explore, the annotation looks correctly configured in the UI, and it just silently produces nothing. I only found the cause by noticing the same annotation config worked on a second dashboard where the equivalent variable was dashboard-global instead of tab-scoped, then confirming via the devtools inspecting the request made and also via the OpenAPI schema that tab specs simply have no annotations field.

What would you like to be added:

Either of these would resolve it:

  1. Add an annotations field to DashboardTabsLayoutTabSpec, so an annotation can be scoped to the tab whose local variables it depends on - mirroring how variables already works per-tab.
  2. If full tab-scoped annotations are out of scope, at minimum surface a warning when a dashboard-global annotation query references a variable that's tab-scoped and therefore unresolvable at evaluation time (e.g. a warning icon on the annotation list item, or a dashboard-JSON validation warning) instead of failing silently.

Who is this feature for?

Anyone using TabsLayout with per-tab (section) variables (something the dashboardSectionVariables toggle explicitly enables) who also wants a restart/event/deploy-style annotation overlay scoped to that same tab's selection. Currently this combination is a dead end with no diagnostic signal.