夜莺-Nightingale
夜莺V7
项目介绍 功能概览
部署升级 部署升级
数据接入 数据接入
告警管理 告警管理
数据查看 数据查看
功能介绍 功能介绍
API FAQ
夜莺V6
项目介绍 架构介绍
快速开始 快速开始
黄埔营
安装部署 安装部署
升级
采集器 采集器
使用手册 使用手册
API API
数据库表结构 数据库表结构
FAQ FAQ
开源生态
Prometheus
版权声明
第1章:天降奇兵 第1章:天降奇兵
第2章:探索PromQL 第2章:探索PromQL
第3章:Prometheus告警处理 第3章:Prometheus告警处理
第4章:Exporter详解 第4章:Exporter详解
第5章:数据与可视化 第5章:数据与可视化
第6章:集群与高可用 第6章:集群与高可用
第7章:Prometheus服务发现 第7章:Prometheus服务发现
第8章:监控Kubernetes 第8章:监控Kubernetes
第9章:Prometheus Operator 第9章:Prometheus Operator
参考资料

模板函数介绍

本文档将详细介绍 Nightingale 监控系统中所有可用的模板函数,包括使用说明和示例。

目录


附加查询函数

query

功能描述:执行 Prometheus 查询并返回结果。这是一个特殊的模板函数,用于在告警注解中动态查询指标数据。

函数签名

func(promql string, param ...int64) QueryResult

参数说明

  • promql: Prometheus 查询语句
  • param: 可选参数,指定数据源 ID。如果不指定,使用当前告警规则的数据源

返回值QueryResult 类型,包含查询结果的样本数据,每个样本包含:

  • Labels: map[string]string 类型的标签集合
  • Value: float64 类型的数值

使用示例

  1. 查询监控指标
{{ $metrics := query "mem_available_percent" }}
{{ range $metrics }}
  机器: {{ .Labels.ident }}
  内存使用率: {{ .Value }}
{{ end }}

可以在告警规则的附加信息中,使用此模板函数来实现告警时查询额外信息的需求
tOuD8l

  1. 查询监控指标使用告警事件某个标签过滤
{{ $metrics := query "mem_available_percent" }}
{{ range $metrics }}
  机器: {{ .Labels.ident }}
  内存使用率: {{ .Value }}
{{ end }}

格式化函数

humanize

功能描述:将数字格式化为人类可读的形式,使用 SI 前缀(k, M, G, T 等)

使用示例

{{ "1234567" | humanize }}     // 输出: 1.23M
{{ "0.00123" | humanize }}      // 输出: 1.23m
{{ "1000000000" | humanize }}   // 输出: 1.00G

humanize1024

功能描述:将数字格式化为人类可读的形式,使用二进制前缀(Ki, Mi, Gi, Ti 等)

使用示例

{{ "1048576" | humanize1024 }}    // 输出: 1Mi
{{ "1073741824" | humanize1024 }} // 输出: 1Gi
{{ "2048" | humanize1024 }}       // 输出: 2ki

humanizeDuration

功能描述:将秒数转换为人类可读的时间格式

使用示例

{{ "3661" | humanizeDuration }}   // 输出: 1h 1m 1s
{{ "86400" | humanizeDuration }}  // 输出: 1d 0h 0m 0s
{{ "0.5" | humanizeDuration }}    // 输出: 500ms

humanizePercentage

功能描述:将小数转换为百分比格式(乘以100)

使用示例

{{ "0.8567" | humanizePercentage }}  // 输出: 85.67%
{{ "0.05" | humanizePercentage }}    // 输出: 5.00%
{{ "1" | humanizePercentage }}       // 输出: 100.00%

humanizePercentageH

功能描述:直接格式化为百分比(不乘以100)

使用示例

{{ "85.67" | humanizePercentageH }}  // 输出: 85.67%
{{ "5" | humanizePercentageH }}      // 输出: 5.00%
{{ "100" | humanizePercentageH }}    // 输出: 100.00%

formatDecimal

功能描述:格式化数字为指定小数位数

使用示例

{{ formatDecimal "3.14159" 2 }}   // 输出: 3.14
{{ formatDecimal "10.5" 3 }}      // 输出: 10.500
{{ formatDecimal "0.123456" 4 }}  // 输出: 0.1235

printf

功能描述:格式化输出字符串,特别优化了对字符串数字的处理(会自动尝试将字符串转换为浮点数)

函数签名

func Printf(format string, value interface{}) string

特点

  • 如果传入的是字符串类型的数字,会自动转换为浮点数进行格式化
  • 支持标准的 Go 格式化占位符

使用示例

// 格式化浮点数(字符串会自动转换)
{{ printf "%.2f" "3.14159" }}        // 输出: 3.14
{{ printf "%.2f" .TriggerValue }}    // 将触发值格式化为2位小数

// 百分比格式化
{{ printf "%.1f%%" "85.67" }}        // 输出: 85.7%
{{ printf "使用率: %.2f%%" .TriggerValue }}  // 输出: 使用率: 85.67%

// 科学计数法
{{ printf "%e" "1234567" }}          // 输出: 1.234567e+06
{{ printf "%.2e" .TriggerValue }}    // 输出: 8.57e+01

// 整数格式化(需要注意类型)
{{ printf "%d" 42 }}                 // 输出: 42

// 字符串格式化
{{ printf "主机 %s 告警" .TagsMap.hostname }}  // 输出: 主机 server01 告警

// 组合使用
{{ printf "[%s] %.2f%% (阈值: %.0f%%)" .RuleName .TriggerValue 80.0 }}
// 输出: [CPU告警] 85.67% (阈值: 80%)

字符串处理函数

escape

功能描述:URL 路径转义

使用示例

{{ "hello world" | escape }}    // 输出: hello%20world
{{ "a/b/c" | escape }}          // 输出: a%2Fb%2Fc

unescaped

功能描述:将字符串作为 HTML 输出(不转义)

使用示例

{{ "<b>Bold Text</b>" | unescaped }}  // 输出原始HTML: <b>Bold Text</b>
{{ "<script>alert('hi')</script>" | unescaped }}  // 输出原始脚本标签

urlconvert

功能描述:将字符串转换为 URL 类型

使用示例

{{ "http://example.com" | urlconvert }}  // 转换为URL类型

toUpper

功能描述:转换为大写

使用示例

{{ "hello world" | toUpper }}  // 输出: HELLO WORLD
{{ .TagsMap.env | toUpper }}    // 将标签值转为大写

toLower

功能描述:转换为小写

使用示例

{{ "HELLO WORLD" | toLower }}  // 输出: hello world
{{ .TagsMap.DC | toLower }}     // 将标签值转为小写

title

功能描述:将字符串转换为标题格式(首字母大写)

使用示例

{{ "hello world" | title }}    // 输出: Hello World
{{ "api_server" | title }}     // 输出: Api_Server

contains

功能描述:检查字符串是否包含子串

使用示例

{{ if contains "hello world" "world" }}包含{{ end }}  // 输出: 包含
{{ if contains .TagsMap.service "api" }}API服务{{ end }}

match

功能描述:正则表达式匹配

使用示例

{{ if match "^prod-.*" .TagsMap.env }}生产环境{{ end }}
{{ if match "[0-9]+" "abc123" }}包含数字{{ end }}

reReplaceAll

功能描述:正则表达式替换

使用示例

{{ reReplaceAll "[0-9]+" "X" "abc123def456" }}  // 输出: abcXdefX
{{ reReplaceAll "\\s+" "-" "hello  world" }}    // 输出: hello-world

split

功能描述:字符串分割

使用示例

{{ split "a,b,c" "," }}         // 返回: ["a", "b", "c"]
{{ range .TagsJSON }}
  标签: {{ . }}
{{ end }}

join

功能描述:字符串连接

使用示例

{{ join (split "a,b,c" ",") "-" }}  // 输出: a-b-c
{{ $arr := args "hello" "world" }}
{{ join $arr " " }}                 // 输出: hello world

toString

功能描述:将任意类型转换为字符串

使用示例

{{ toString 123 }}           // 输出: "123"
{{ toString 3.14 }}          // 输出: "3.14"
{{ toString .Value }}        // 将数值转为字符串

时间处理函数

timeformat

功能描述:格式化 Unix 时间戳

使用示例

{{ timeformat 1609459200 }}                       // 输出: 2021-01-01 00:00:00
{{ timeformat 1609459200 "2006-01-02" }}         // 输出: 2021-01-01
{{ timeformat .Timestamp "15:04:05" }}           // 输出时间部分

timestamp

功能描述:获取当前时间的格式化字符串

使用示例

{{ timestamp }}                     // 输出: 2024-01-15 10:30:45
{{ timestamp "2006-01-02" }}       // 输出: 2024-01-15
{{ timestamp "15:04:05" }}         // 输出: 10:30:45

now

功能描述:获取当前时间对象

使用示例

{{ now }}                          // 返回当前时间对象
{{ now.Format "2006-01-02" }}     // 格式化当前时间
{{ now.Unix }}                     // 获取Unix时间戳

toTime

功能描述:将时间戳转换为时间对象

使用示例

{{ $t := toTime 1609459200 }}
{{ $t.Format "2006-01-02" }}      // 输出: 2021-01-01

parseDuration

功能描述:解析时间持续时间字符串

使用示例

{{ parseDuration "1h30m" }}       // 返回: 5400 (秒)
{{ parseDuration "24h" }}         // 返回: 86400 (秒)
{{ parseDuration "5m" }}          // 返回: 300 (秒)

数学运算函数

add

功能描述:加法运算

使用示例

{{ add 10 20 }}                   // 输出: 30

sub

功能描述:减法运算

使用示例

{{ sub 100 30 }}                  // 输出: 70

mul

功能描述:乘法运算

使用示例

{{ mul 10 5 }}                    // 输出: 50

div

功能描述:除法运算

使用示例

{{ div 100 5 }}                   // 输出: 20

数据处理函数

first

功能描述:获取查询结果的第一个元素

函数签名

func(v QueryResult) (*sample, error)

使用示例

{{ $result := query "up" }}
{{ with first $result }}
  第一个实例: {{ label "instance" . }} 状态: {{ value . }}
{{ end }}

// 注意:在 AlertCurEvent 上下文中访问标签应使用 TagsMap
第一个触发的主机: {{ .TagsMap.hostname }}

label

功能描述:获取查询结果样本的标签值(用于 query 函数返回的 QueryResult的单个 sample )

函数签名

func(label string, s *sample) string

使用示例

{{ $result := query "up" }}
{{ range $result }}
  主机名: {{ label "hostname" . }}
  环境: {{ label "env" . }}
{{ end }}

value

功能描述:获取查询结果样本的数值(用于 query 函数返回的 QueryResult 的单个 sample)

函数签名

func(s *sample) float64

使用示例

{{ $result := query "cpu_usage" }}
{{ range $result }}
  CPU使用率: {{ value . }}%
{{ end }}

模板渲染上下文(AlertCurEvent)

在告警规则的注解和通知模板渲染时,模板引擎会传入 AlertCurEvent 对象作为上下文。你可以直接访问该对象的所有字段。

预定义变量

模板开始时会自动定义以下便捷变量:

  • $labels: 等同于 .TagsMap,包含所有标签的键值对
  • $value: 等同于 .TriggerValue,触发告警的值
  • $annotations: 等同于 .AnnotationsJSON,注解的键值对(仅在某些场景可用)

AlertCurEvent 主要字段

字段 类型 说明 使用示例
.Id int64 告警事件ID 告警ID: {{ .Id }}
.Cate string 告警类别 类别: {{ .Cate }}
.Cluster string 集群名称 集群: {{ .Cluster }}
.DatasourceId int64 数据源ID 数据源: {{ .DatasourceId }}
.GroupId int64 业务组ID 业务组ID: {{ .GroupId }}
.GroupName string 业务组名称 业务组: {{ .GroupName }}
.RuleId int64 规则ID 规则ID: {{ .RuleId }}
.RuleName string 规则名称 规则: {{ .RuleName }}
.RuleNote string 规则备注 备注: {{ .RuleNote }}
.RuleProd string 规则产品线 产品线: {{ .RuleProd }}
.RuleAlgo string 规则算法 算法: {{ .RuleAlgo }}
.Severity int 告警级别(1-3) {{ if eq .Severity 1 }}P1级告警{{ end }}
.PromQl string PromQL查询语句 查询: {{ .PromQl }}
.PromForDuration int 持续时间阈值(秒) 持续: {{ .PromForDuration }}秒
.PromEvalInterval int 评估间隔(秒) 评估间隔: {{ .PromEvalInterval }}秒
.RunbookUrl string 运维手册URL <a href="{{ .RunbookUrl }}">运维手册</a>
.TargetIdent string 目标标识 目标: {{ .TargetIdent }}
.TargetNote string 目标备注 {{ .TargetNote }}
.TriggerTime int64 触发时间戳 {{ .TriggerTime | timeformat }}
.TriggerValue string 触发值 当前值: {{ .TriggerValue }}
.TagsMap map[string]string 标签键值对 主机: {{ .TagsMap.hostname }}
.TagsJSON []string 标签数组 {{ range .TagsJSON }}{{ . }} {{ end }}
.AnnotationsJSON map[string]string 注解键值对 {{ .AnnotationsJSON.description }}
.NotifyChannels []string 通知渠道 {{ range .NotifyChannelsJSON }}{{ . }}{{ end }}
.NotifyGroups []string 通知组 {{ range .NotifyGroupsJSON }}{{ . }}{{ end }}
.NotifyCurNumber int 当前通知次数 第{{ .NotifyCurNumber }}次通知
.FirstTriggerTime int64 首次触发时间 首次告警: {{ .FirstTriggerTime | timeformat }}
.Claimant string 认领人 认领人: {{ .Claimant }}

使用示例

// 基础信息访问
告警名称:{{ .RuleName }}
告警级别:{{ if eq .Severity 1 }}P1{{ else if eq .Severity 2 }}P2{{ else }}P3{{ end }}
业务组:{{ .GroupName }}
触发时间:{{ .TriggerTime | timeformat "2006-01-02 15:04:05" }}
当前值:{{ .TriggerValue | humanize }}

// 使用预定义变量
主机名:{{ $labels.ident }}
当前值:{{ $value | humanizePercentage }}

// 条件判断
{{ if gt (toFloat64 .TriggerValue) 80 }}
严重:使用率超过80%
{{ else if gt (toFloat64 .TriggerValue) 60 }}
警告:使用率超过60%
{{ end }}

// 遍历标签
{{ range $k, $v := .TagsMap }}
  {{ $k }}: {{ $v }}
{{ end }}

// 访问注解
描述:{{ .AnnotationsJSON.description }}
摘要:{{ .AnnotationsJSON.summary }}
快猫星云 联系方式 快猫星云 联系方式
快猫星云 联系方式
快猫星云 联系方式
快猫星云 联系方式
快猫星云
OpenSource
开源版
Flashcat
Flashcat