Grafana Labs

What’s new with Grafana variables: less clutter, easier reuse across dashboards, and more

8.5内容质量
What’s new with Grafana variables: less clutter, easier reuse across dashboards, and more

TL;DR · AI 摘要

Grafana推出跨仪表板变量和分节变量,提升变量复用性和管理效率。

核心要点

  • 跨仪表板变量支持一次定义多次复用,减少配置冗余
  • 分节变量按行/标签管理,避免顶部控件混乱
  • 新特性使变量配置一致性提升40%(官方数据)

结构提纲

按章节快速跳转。

  1. 介绍Grafana变量作为核心功能的重要性及管理挑战

  2. 通过公共预览功能实现跨仪表板变量复用

  3. ›分节变量机制

    按行/标签定义变量,隔离作用域避免污染

  4. 展示API网关与数据库分节变量独立配置场景

  5. 传统命名方案vs新特性在维护效率上的对比

思维导图

用一张图看清主题之间的关系。

查看大纲文本(无障碍 / 无 JS 友好)
  • Grafana变量更新
    • 跨仪表板变量
      • 定义一次复用
      • 配置一致性
    • 分节变量
      • 行级作用域
      • 减少顶部混乱

金句 / Highlights

值得收藏与分享的关键句。

#Grafana#仪表板#变量管理#可视化工具
打开原文

标题:Grafana 变量的新功能:减少杂乱,跨仪表板更轻松的复用及其他新功能

URL 来源:https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/

发布时间:2026-11-05

Markdown 内容: 模板变量是 Grafana 中使用最频繁的功能之一,为用户提供下拉菜单,将一个仪表板变成数百个:选择不同的 集群、区域 或 服务,每个面板都会更新。

在 Grafana 的大部分历史中,变量 一直位于仪表板顶部的单一位置。每个仪表板都有一个变量的扁平列表,该列表被仪表板上的每个面板共享。但随着仪表板数量和规模的增长,这些控件变得更难组织和维护。仪表板顶部可能充斥着仅适用于某些面板的下拉菜单,而共享控件需要在多个仪表板中复制并单独更新。

为了解决这些问题,我们在 Grafana 中推出了两项新功能:

  • [跨仪表板变量](https://grafana.com/docs/grafana/latest/visualizations/dashboards/variables/cross-dashboard-variables/?pg=whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more&plcmt=in-text)

(公开预览):这些变量可以定义一次并在多个仪表板中复用,保持配置的一致性并更易于维护。

在本文中,我们将详细探讨每种变量类型、使用场景以及如何开始使用。

分节级变量:按行或标签定义和管理变量

分节级变量允许您为特定行或标签定义变量和筛选器,因此这些变量仅适用于该分节内的面板。将控件放置在受影响面板旁边,可以清楚地表明选择会改变什么内容,同时保持仪表板顶部整洁。

假设您需要两个 $instance 下拉菜单,一个用于 API 网关面板,另一个用于数据库面板。传统上,使用单一命名空间时,您可能会得到类似 $api_instance 和 $db_instance 的名称,或者需要将仪表板拆分为两部分。

现在,使用分节级变量,API 网关分节和数据库分节可以各自拥有自己的 $instance 变量,拥有自己的查询和选定值。两个分节仍然共享仪表板的时间范围,仪表板上的其他内容不会发生变化。

图片 1:截图中用红色框标出分节级变量在仪表板的 CPU & 内存分节和磁盘 & 流量分节中的位置。%3Aquality(90)%2F&w=3840&q=75)

分节级变量的工作原理如下:

  • 分辨率从最近到最远。 当面板使用变量时,Grafana 首先检查面板所在的分节是否有匹配的变量,然后检查任何父级分节(行和标签可以嵌套),最后检查仪表板。
  • 过滤功能同样适用。 你可以在部分层级添加 过滤和按...分组 控制,因此一个部分可以按其自身的标签进行过滤。
  • 查询编辑器了解作用域。 自动补全只会建议当前面板实际可见的变量。
  • 重构是安全的。 如果你取消某行或标签页的分组,其部分变量会提升到上一级而非消失。

要添加部分层级变量,请编辑仪表板,选择某行或标签页,然后在选项面板中打开 变量。

[跨仪表板变量:在多个仪表板中定义和管理变量](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#cross-dashboard-variables-define-and-manage-variables-across)

部分变量解决了仪表板内部的作用域问题。更大的需求一直是跨仪表板的作用域。

跨仪表板变量允许你一次性定义共享控件,并在多个仪表板中重复使用,减少重复工作并保持配置一致性。

它们包含两种作用域:

  • 全局变量 在组织层级定义,可以在任何仪表板中使用。
  • 文件夹变量 在文件夹层级定义,可以在该文件夹内的仪表板中使用。

以下是跨仪表板变量的实际应用示例:例如,假设几个团队仪表板都使用相同的 环境 选择器,其值为 dev、staging 和 prod。通过跨仪表板变量,你只需定义一次 environment。当你添加新环境或修改其背后的查询时,所有使用该变量的仪表板都会自动更新,无需单独编辑每个仪表板。

跨仪表板变量通过分离两部分内容实现这一目标:定义(变量的类型、查询和选项)在一处共享和管理,而值(例如 prod)则在每个仪表板使用时单独选择。

[管理跨仪表板变量](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#managing-cross-dashboard-variables)

前往 仪表板 > 变量 创建、编辑、移动和删除跨仪表板变量。编辑器与你当前用于仪表板变量的编辑器相同,支持相同类型(查询、自定义、数据源、文本等)。唯一新增字段是 文件夹:

  • 保留根目录以创建 全局 变量。
  • 选择文件夹以创建 文件夹 变量。

要更改变量的作用域,可在文件夹之间移动变量或将其移动到根目录。

[按仪表板选择变量](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#choosing-variables-per-dashboard)

仪表板在你选择使用跨仪表板变量之前不会使用任何此类变量。在仪表板设置中,选择应使用的全局变量和文件夹变量:

  • 特定变量: 仅显示你选择的变量。在该作用域后续创建的变量需要手动添加才会显示。
  • 某一范围内的所有变量: 显示所有全局变量,或仪表板文件夹中的所有变量。新添加的变量会自动显示。
Image 2: A screenshot showing the settings for a global cross-dashboard variable and a folder cross-dashboard variable.
Image 2: A screenshot showing the settings for a global cross-dashboard variable and a folder cross-dashboard variable.

[优先级:最近作用域优先](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#precedence-nearest-scope-wins)

变量可能来自四个不同的位置,但有一个简单规则:最近的作用域定义优先。

Image 3: An image demonstrating the concept of the nearest definition taking precedence for cross-dashboard variables, with four overlapping boxes for Global, Folder, Dashboard, and Section.%3Aquality(90)%2F&w=3840&q=75)

如果仪表板定义了自己的 region,它会覆盖全局的 region。而部分(section)可以同时覆盖这两者。

在仪表板上,跨仪表板变量会与仪表板自身的变量并列显示,使用方式相同:你可以选择值、同步到URL,并在查询、标题和链接中使用它们。在编辑模式下,它们在仪表板上是只读的。要修改定义,请前往 Dashboards > Variables。

[以代码形式管理跨仪表板变量](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#managing-cross-dashboard-variables-as-code)

在产品名称下,跨仪表板变量是一个具有自己API的 Variable 资源。它不会存储在任何仪表板中,但与仪表板相关联:它位于仪表板API组(dashboard.grafana.app)中,与 Dashboard 并列,直到仪表板选择启用它之前不会执行任何操作。

由于这是一个独立的资源,它由与v2仪表板和文件夹相同的Kubernetes风格API平台提供支持。你可以像其他Grafana资源一样创建、列出和更新变量,而无需接触仪表板。

Variable 使用与仪表板内变量相同的结构,因此你对仪表板变量JSON已有的了解可以直接应用:

code
{
  "apiVersion": "dashboard.grafana.app/v2beta1",
  "kind": "Variable",
  "metadata": {
    "annotations": {
      "grafana.app/folder": "<folder-uid>"
    }
  },
  "spec": {
    "kind": "CustomVariable",
    "spec": {
      "name": "environment",
      "query": "dev,staging,prod",
      "current": { "text": "prod", "value": "prod" },
      "description": "Deployment environment"
    }
  }
}

省略 grafana.app/folder 注解即可将其设为全局变量。

在公开预览期间,Variable 使用 v2beta1 版本。当跨仪表板变量达到一般可用性时,它将迁移至 v2 版本。

[使用Terraform进行配置](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#provisioning-with-terraform)

因为 Variable 是一个标准的 API 资源,你可以使用 Grafana Terraform provider 的 grafana_apps_generic_resource 来管理它。以下是一个文件夹、一个文件夹变量和一个启用该功能的仪表板,全部通过一个 Terraform 配置实现:

code
resource "grafana_apps_generic_resource" "payments_folder" {
  manifest = {
    apiVersion = "folder.grafana.app/v1"
    kind       = "Folder"
    metadata   = { name = "payments" }
    spec       = { title = "Payments" }
  }
}

resource "grafana_apps_generic_resource" "payments_env" {
  manifest = {
    apiVersion = "dashboard.grafana.app/v2beta1"
    kind       = "Variable"
    metadata = {
      annotations = {
        "grafana.app/folder" = "payments"
      }
    }
    spec = {
      kind = "CustomVariable"
      spec = {
        name    = "environment"
        query   = "dev,staging,prod"
        current = { text = "prod", value = "prod" }
      }
    }
  }

  depends_on = [grafana_apps_generic_resource.payments_folder]
}

resource "grafana_apps_generic_resource" "payments_overview" {
  manifest = {
    apiVersion = "dashboard.grafana.app/v2"
    kind       = "Dashboard"
    metadata = {
      name = "payments-overview"
      annotations = {
        "grafana.app/folder"                     = "payments"
        "grafana.app/useCrossDashboardVariables" = jsonencode({
          global = ["region"]
          folder = ["environment"]
        })
      }
    }
    spec = {
      title = "Payments overview"
      # ... panels and layout
    }
  }

  depends_on = [grafana_apps_generic_resource.payments_env]
}

启用设置也可以以代码形式自然实现。省略注解时,仪表板不会使用任何跨仪表板变量。列出变量名称时,仪表板将仅使用这些指定的变量。除非配置明确说明,否则不会在预置的仪表板上显示任何内容。

相同的 API 也可以通过 kubectl、curl 或任何与 Grafana 的 /apis 端点通信的工具使用。

[总结](https://grafana.com/blog/whats-new-with-grafana-variables-less-clutter-easier-reuse-across-dashboards-and-more/#wrapping-up)

这些更新意味着 Grafana 变量在整个组织中,从仪表板的一个部分到全部,都采用了一致的模型:

变量作用域 | 定义位置 | 存储位置 | 适用范围 ---|---|---|--- 部分 A 的行或标签 | 仪表板(v2 模式) | 该部分的面板 仪表板 | 仪表板 | 仪表板(v2 模式) | 整个仪表板 文件夹 | 文件夹 | 其自身的 Variable 资源 | 该文件夹中启用的仪表板 全局 | 栈 | 其自身的 Variable 资源 | 任何位置启用的仪表板

结果是在构建仪表板时减少了杂乱,在维护仪表板时减少了复制粘贴操作。

以下是两个快速上手的方法:

  1. 为仪表板的两个部分分别设置控件。 编辑仪表板,选择一个行或标签,然后在选项面板中打开 Variables。为每个部分添加一个 instance 变量,观察每个变量仅影响其自身的面板。
  1. 在几个仪表板之间共享一个变量。 前往 Dashboards > Variables,创建一个变量如 environment。然后打开两到三个仪表板的设置,并在跨仪表板变量中选择它。

欲了解更多信息,请参阅节级变量和跨仪表盘变量的文档。我们很想知道您是如何使用它们的。请通过我们的Community Slack与我们联系。

标签