首页/云/可观测性速查/变量级联:先选上层再展开下层
Grafana 与看板53 条

变量级联:先选上层再展开下层

下级变量的候选由上级变量决定:把上级值写进下级的查询里(如 {job="$job"}),实现按任务过滤实例的逐级筛选。

可观测性速查云更新于 2026-10-13

变量级联是什么

变量级联让下级变量的候选值由上级变量决定:把上级变量的引用写进下级的查询里,例如实例变量的查询里带上 job 的取值,于是先选任务、再选实例,列表自然收窄。它解决的是标签候选集太大的问题——几千个实例平铺在一个下拉框里几乎没法用,级联之后每一步的候选都控制在可读范围内。

基本信息

适用版本Grafana 8+
依赖关系下级变量的查询中引用上级变量
变量顺序变量列表的排列顺序决定刷新依赖
常用函数label_values、query_result
注意点多选变量嵌入查询需配套 allValue 与正则

典型使用场景

  • 实例选择:先选任务或服务,再选实例,避免几千条候选值
  • 命名空间到工作负载:Kubernetes 场景先选命名空间再选工作负载
  • 区域到集群:先选区域再选集群,跨区域看板更好用
  • 指标到标签:先选指标名,再选该指标上实际存在的标签值
  • 业务线到接口:先选业务线再选接口路径,排查时定位更快

使用要点

  • 变量顺序要把上级拖到下级前面,顺序错了下级会一直空着
  • 多选变量嵌入下级查询要配合 allValue 或正则写法,否则语法报错
  • 级联层数不宜过多,两到三层已经足够,再多会让看板加载变慢
  • 上级变量变化会触发下级重新查询,刷新频率高的看板要注意负载
  • 用 Explore 或 Graph 页验证每一层的查询是否返回预期候选

级联写法

级联写法
# 变量 job:label_values(up, job)
# 变量 instance:
label_values(up{job="$job"}, instance)

# 想再按指标名缩小候选,可以加上度量名:
label_values(node_uname_info{job="$job"}, instance)

# 多选变量的正则写法(需配套 allValue)
label_values(up{job=~"$job"}, instance)

常见表现与原因

现象原因处理方向
下级一直为空变量顺序或引用写错把上级拖到下级前面并核对查询
候选不随上级变化下级查询未引用上级变量在下级查询里补上过滤条件
选全部时报错多选变量未配套 allValue补齐 allValue 与正则写法
加载变慢级联层数过多或刷新过快收敛到两三层并降低刷新频率
取值匹配不上标签值大小写敏感直接复制标签值而不是手写
级联的本质是把一次大范围查询拆成几步逐步收窄,它同时降低了后端压力与人工选择成本,是看板可维护性最直接的改善之一。

易错点

  • 下级的查询里引用了尚未初始化的上级变量时返回空列表,先看变量顺序再看查询语句
  • 多选变量直接嵌入下级查询需要 allValue 与正则配合,否则会出现语法错误
  • 级联层数堆到四五层后,看板每次打开都会发起大量查询,加载明显变慢
  • 标签值大小写敏感,手写的取值与真实标签不一致时列表为空且没有任何提示

数据来源与参考

  • Grafana 官方文档 · Chained variables
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌