模板函数介绍
本文档将详细介绍 Nightingale 监控系统中所有可用的模板函数,包括使用说明和示例。
目录
附加查询函数
query
功能描述:执行 Prometheus 查询并返回结果。这是一个特殊的模板函数,用于在告警注解中动态查询指标数据。
函数签名:
func(promql string, param ...int64) QueryResult
参数说明:
promql
: Prometheus 查询语句param
: 可选参数,指定数据源 ID。如果不指定,使用当前告警规则的数据源
返回值:QueryResult
类型,包含查询结果的样本数据,每个样本包含:
Labels
: map[string]string 类型的标签集合Value
: float64 类型的数值
使用示例:
- 查询监控指标
{{ $metrics := query "mem_available_percent" }}
{{ range $metrics }}
机器: {{ .Labels.ident }}
内存使用率: {{ .Value }}
{{ end }}
可以在告警规则的附加信息中,使用此模板函数来实现告警时查询额外信息的需求
- 查询监控指标使用告警事件某个标签过滤
{{ $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 }}