如何在Prometheus的with query语法中正确使用{{ $labels.instance }}

在Alertmanager的alert.yaml注解中，要正确将{{ $labels.instance }}嵌入PromQL查询，核心是用Go模板的printf函数安全拼接查询语句，避免手动转义引号的混乱。

问题根源 #

直接在query函数的字符串中嵌套模板变量或手动转义单引号，会导致生成的PromQL语法错误（比如标签值未被正确包裹），或者模板解析失败。

正确写法示例 #

annotations:
  currentNumber: >-
    {{ $instance := $labels.instance }}
    {{ with query (printf "sum(your_metric_name{instance=''%s''})" $instance) }}
      {{ . | first | value | printf "%.2f" }}
    {{ else }}
      N/A
    {{ end }}

关键说明 #

• 用printf构建查询：''在Go模板中代表转义单引号，这样生成的PromQL会自动为instance标签值加上单引号，符合PromQL语法规范。
• 变量赋值简化模板：先将$labels.instance赋值给$instance变量，提升模板可读性。
• 处理查询结果：
  • | first | value：取出查询结果的第一个样本值（适用于单结果查询场景）。
  • | printf "%.2f"：可选，格式化数值为两位小数，避免科学计数法或过长小数。
  • else分支：当查询无结果时显示N/A，防止注解内容为空。

常见错误写法对比 #

# 错误：直接嵌入变量导致PromQL语法错误（instance值未被引号包裹）
currentNumber: '{{ with query "sum(metric{instance={{ $labels.instance }}})" }}{{ . | first | value }}{{ end }}'

# 错误：转义方式不正确，模板解析失败
currentNumber: '{{ with query "sum(metric{instance=\'{{ $labels.instance }}\'})" }}{{ . | first | value }}{{ end }}'

内容的提问来源于stack exchange，提问作者Bruce