- 快猫星云Flashcat

夜鶯監控系統中所有可用的範本函式參考，包括使用說明和範例。

本文件將詳細介紹 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 }}

可以在告警規則的附加資訊中，使用此範本函式來實現告警時查詢額外資訊的需求 tOuD8l

查詢監控指標時，使用告警事件某個標籤過濾

{{ $memMetrics := query (printf "mem_available_percent{ident=\"%s\"}" .TagsMap.ident) }}
{{ range $memMetrics }}
  机器: {{ .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 }}

常見問題

Q1：範本函式和 Go 標準 template 的區別？

A：n9e 在 Go 標準 template 的基礎上擴充了告警場景專用函式（時間格式化、單位轉換、字串處理、JSON 解析等）。所有擴充函式實現在 tplx.go 裡。

Q2：範本除錯時報「undefined function」怎麼辦？

A：函式名拼錯了，或者你用的是某個舊版本不支援的函式。檢查 tplx.go 裡有沒有這個函式名，對應 n9e Server 版本。

Q3：能不能自訂範本函式？

A：目前需要修改 n9e 原始碼 + 重新編譯。社群版方法：

在 tplx.go 裡加自訂函式；
註冊到 funcMap；
重新編譯 server。

Q4：範本裡時間顯示成時間戳了，怎麼轉人類可讀？

A：用 timeformat：{{timeformat .LastEvalTime}} 輸出 2026-05-19 15:30:00；想要自訂格式用 timeformat <欄位> "2006-01-02 15:04:05"（Go 時間格式）。

目錄

附加查詢函式

query

格式化函式

humanize

humanize1024

humanizeDuration

humanizePercentage

humanizePercentageH

formatDecimal

printf

字串處理函式

escape

unescaped

urlconvert

toUpper

toLower

title

contains

match

reReplaceAll

split

join

toString

時間處理函式

timeformat

timestamp

now

toTime

parseDuration

數學運算函式

add

sub

mul

div

資料處理函式

first

label

value

範本渲染上下文（AlertCurEvent）

預定義變數

AlertCurEvent 主要欄位

使用範例

常見問題

參考資料