本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 範本標籤和註釋
****
本文件主題專為支援 Grafana **9.x 版的 Grafana** 工作區而設計。
如需支援 Grafana 10.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 10 版](using-grafana-v10.md)。
如需支援 Grafana 8.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 8 版](using-grafana-v8.md)。
在 Grafana 中，您會像在 Prometheus 中一樣範本標籤和註釋。如果您之前已使用 Prometheus，則應熟悉 `$labels`和 `$value`變數，其中包含提醒的標籤和值。您可以在 Grafana 中使用相同的變數，即使提醒不使用 Prometheus 資料來源。如果您之前沒有使用 Prometheus，則不必擔心這些變數的每一個，以及如何建立範本，當您遵循本頁面的其餘部分時，將會進行說明。
## Go 的範本語言
標籤和註釋的範本是以 Go 的範本語言[文字/範本](https://pkg.go.dev/text/template)撰寫。
**開啟和關閉標籤**
在文字/範本中，無論範本`}}`是否列印變數或執行控制結構，例如 if 陳述式，範本都會以 開頭`{{`和結尾。這與其他範本語言不同，例如 Jinja，其中列印變數使用 `{{`和 `}}`，控制結構使用 `{%`和 `%}`。
**Print (列印)**
若要列印某個項目的值，請使用 `{{`和 `}}`。您可以列印函數的結果或變數的值。例如，若要列印`$labels`變數，您會撰寫下列項目：
```
{{ $labels }}
```
**在標籤上反覆運算**
若要逐一查看 中的每個標籤`$labels`，您可以使用 `range`。這裡`$k`是指名稱，而 `$v` 是指目前標籤的值。例如，如果您的查詢傳回標籤`instance=test`，則 `$k`會是 `instance`，而 `$v` 會是 `test`。
```
{{ range $k, $v := $labels }}
{{ $k }}={{ $v }}
{{ end }}
```
## 標籤、值和值變數
**標籤變數**
`$labels` 變數包含查詢中的標籤。例如，檢查執行個體是否關閉的查詢可能會傳回執行個體標籤，其名稱為關閉的執行個體。例如，假設您有一個警示規則，當其中一個執行個體停機超過 5 分鐘時，就會觸發該規則。您想要將摘要新增至提醒，告知您哪個執行個體已關閉。使用 `$labels`變數，您可以建立摘要，在摘要中列印執行個體標籤：
```
Instance {{ $labels.instance }} has been down for more than 5 minutes
```
**帶有點的標籤**
如果您想要列印的標籤在範本中使用相同點的名稱中包含點 （完全停止或句點） 將無法運作：
```
Instance {{ $labels.instance.name }} has been down for more than 5 minutes
```
這是因為範本嘗試使用 `name`中稱為 的不存在欄位`$labels.instance`。您應該改用 函數，該`index`函數會在 `$labels`變數`instance.name`中列印標籤：
```
Instance {{ index $labels "instance.name" }} has been down for more than 5 minutes
```
**值變數**
`$value` 變數的運作方式與 Prometheus 不同。在 Prometheus `$value`中，浮點數包含表達式的值，但在 Grafana 中，浮點數包含此提醒規則所有閾值、減少和數學表達式和傳統條件的標籤和值。它不包含查詢的結果，因為它們可以傳回 10s 到 10，000s 的資料列或指標。
如果您要在提醒摘要中使用 `$value`變數：
```
{{ $labels.service }} has over 5% of responses with 5xx errors: {{ $value }})
```
摘要看起來可能會類似以下內容：
```
api has an over 5% of responses with 5xx errors: [ var='B' labels={service=api} value=6.789 ]
```
這裡`var='B'`是指具有 RefID B 的表達式。在 Grafana 中，所有查詢和表達式都是由識別提醒規則中每個查詢和表達式的 RefID 所識別。同樣地， `labels={service=api}` 是指標籤，而 `value=6.789`是指 值。
您可能已觀察到沒有 RefID A。這是因為在大多數提醒規則中，RefID A 是指查詢，而且因為查詢可以傳回許多資料列或時間序列，它們不包含在 中`$value`。
**值變數**
如果`$value`變數包含的資訊超過您需要的資訊，您可以改為使用 列印個別表達式的標籤和值`$values`。與 不同`$value`，`$values`變數是物件的資料表，其中包含每個表達式的標籤和浮點值，依其 RefID 編製索引。
如果您要在提醒摘要`B`中使用 RefID 列印表達式的值：
```
{{ $labels.service }} has over 5% of responses with 5xx errors: {{ $values.B }}%
```
摘要將僅包含 值：
```
api has an over 5% of responses with 5xx errors: 6.789%
```
不過，當 `{{ $values.B }}`列印數字 6.789 時，它實際上是一個字串，因為您列印的物件同時包含 RefID B 的標籤和值，而不是 B 的浮點值。若要使用 RefID B 的浮點值，您必須使用 中的 `Value` 欄位`$values.B`。如果您要人為化警示摘要中的浮點值：
```
{{ $labels.service }} has over 5% of responses with 5xx errors: {{ humanize $values.B.Value }}%
```
**無資料、執行時間錯誤和逾時**
如果警示規則中的查詢未傳回任何資料，或因為資料來源錯誤或逾時而失敗，則使用該查詢的任何閾值、減少或數學表達式也將不會傳回任何資料或錯誤。發生這種情況時，這些表達式將不存在於 `$values`。最佳實務是在使用前檢查 RefID 是否存在，否則，如果您的查詢未傳回資料或發生錯誤，您的範本將會中斷。您可以使用 if 陳述式來執行此操作：
```
{{ if $values.B }}{{ $labels.service }} has over 5% of responses with 5xx errors: {{ humanizePercentage $values.B.Value }}{{ end }}
```
## 傳統條件
如果規則使用 Classic Conditions 而非 Threshold、Reuce 和 Math 運算式，則`$values`變數會以 Classic Condition 中條件的 Ref ID 和位置來編製索引。例如，如果您的 Classic Condition 具有包含兩個條件的 RefID B，則 `$values`將包含兩個條件 `B0`和 `B1`。
```
The first condition is {{ $values.B0 }}, and the second condition is {{ $values.B1 }}
```
## 函數
展開標籤和註釋時，也可以使用下列函數：
**args**
`args` 函數會將物件清單轉譯為索引鍵為 arg0、arg1 等的映射。這是為了允許將多個引數傳遞至 範本。
**範例**
```
{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}}
```
```
1 2
```
**externalURL**
`externalURL` 函數會傳回 Grafana 伺服器的外部 URL，如 ini 檔案 (ini) 中所設定。
**範例**
```
{{ externalURL }}
```
```
https://example.com/grafana
```
**graphLink**
`graphLink` 函數會針對指定的表達式和資料來源，傳回 中圖形檢視[探索 Grafana 第 9 版](v9-explore.md)的路徑。
**範例**
```
{{ graphLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}
```
```
/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}]
```
**人文化**
`humanize` 函數可人為化小數位數。
**範例**
```
{{ humanize 1000.0 }}
```
```
1k
```
**humanize1024**
`humanize1024` 的運作方式類似於 ，`humanize`但使用 1024 做為基礎，而不是 1000。
**範例**
```
{{ humanize1024 1024.0 }}
```
```
1ki
```
**humanizeDuration**
`humanizeDuration` 函數會以秒為單位將持續時間人為化。
**範例**
```
{{ humanizeDuration 60.0 }}
```
```
1m 0s
```
**humanizePercentage**
`humanizePercentage` 函數會將比率值人為化為百分比。
**範例**
```
{{ humanizePercentage 0.2 }}
```
```
20%
```
**humanizeTimestamp**
`humanizeTimestamp` 函數會人為化 Unix 時間戳記。
**範例**
```
{{ humanizeTimestamp 1577836800.0 }}
```
```
2020-01-01 00:00:00 +0000 UTC
```
**比對**
`match` 函數會比對文字與規則表達式模式。
**範例**
```
{{ match "a.*" "abc" }}
```
```
true
```
**pathPrefix**
`pathPrefix` 函數會傳回 Grafana 伺服器的路徑，如 ini 檔案 (ini) 中所設定。
**範例**
```
{{ pathPrefix }}
```
```
/grafana
```
**tableLink**
`tableLink` 函數會針對指定的表達式和資料來源，傳回 中表格式檢視[探索 Grafana 第 9 版](v9-explore.md)的路徑。
**範例**
```
{{ tableLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}
```
```
/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}]
```
**標題**
`title` 函數會大寫每個單字的第一個字元。
**範例**
```
{{ title "hello, world!" }}
```
```
Hello, World!
```
**toLower**
`toLower` 函數會傳回小寫的所有文字。
**範例**
```
{{ toLower "Hello, world!" }}
```
```
hello, world!
```
**toUpper**
`toUpper` 函數會傳回大寫的所有文字。
**範例**
```
{{ toUpper "Hello, world!" }}
```
```
HELLO, WORLD!
```
**reReplaceAll**
`reReplaceAll` 函數會取代符合規則表達式的文字。
**範例**
```
{{ reReplaceAll "localhost:(.*)" "example.com:$1" "localhost:8080" }}
```
```
example.com:8080
```