本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 格式化標籤和註釋
****
本文件主題專為支援 Grafana **10.x 版的 Grafana** 工作區而設計。
如需支援 Grafana 12.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 12 版](using-grafana-v12.md)。
如需支援 Grafana 9.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 9 版](using-grafana-v9.md)。
如需支援 Grafana 8.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 8 版](using-grafana-v8.md)。
您可以使用 範本，在標籤和註釋中包含來自查詢和表達式的資料。例如，您可能想要根據查詢的值設定警示的嚴重性標籤，或在摘要註釋中使用查詢中的執行個體標籤，以便您知道哪個伺服器遇到高 CPU 使用率。
所有範本都應以[文字/範本](https://pkg.go.dev/text/template)撰寫。無論您要範本化標籤或註釋，都應該在範本化的標籤或註釋中內嵌寫入每個範本。這表示您無法在標籤和註釋之間共用範本，而是需要在您想要使用範本的位置複製範本。
每當評估提醒規則時，都會評估每個範本，並針對每個提醒分別進行評估。例如，如果您的提醒規則具有範本摘要註釋，且提醒規則具有 10 個觸發提醒，則範本將執行 10 次，每個提醒一次。您應該盡可能避免在範本中進行昂貴的運算。
## 範例
下列範例會嘗試顯示我們在範本中看到的最常見使用案例，而不是撰寫完整的文字/範本教學課程。您可以逐字使用這些範例，或根據您的使用案例視需要進行調整。如需如何撰寫文字/範本的詳細資訊，請參閱[文字/範本](https://pkg.go.dev/text/template)文件。
**列印所有標籤，以逗號分隔**
若要列印所有標籤，請以逗號分隔，請列印`$labels`變數：
```
{{ $labels }}
```
例如，使用標籤 `alertname=High CPU usage`、 `grafana_folder=CPU alerts`和 提供提醒`instance=server1`，這會列印：
```
alertname=High CPU usage, grafana_folder=CPU alerts, instance=server1
```
**注意**
如果您使用的是傳統條件，則 `$labels`不會包含查詢中的任何標籤。如需詳細資訊[，請參閱 $labels 變數](#v10-alerting-overview-labels-templating-the-labels-variable)。
**列印所有標籤，每行一個**
若要列印所有標籤，每行一個標籤，請使用 `range`逐一查看每個鍵/值對，並個別列印。這裡`$k`是指名稱，而 `$v` 是指目前標籤的值：
```
{{ range $k, $v := $labels -}}
{{ $k }}={{ $v }}
{{ end }}
```
例如，使用標籤 `alertname=High CPU usage`、 `grafana_folder=CPU alerts`和 提供提醒`instance=server1`，這會列印：
```
alertname=High CPU usage
grafana_folder=CPU alerts
instance=server1
```
**注意**
如果您使用的是傳統條件，則 `$labels`不會包含查詢中的任何標籤。如需詳細資訊[，請參閱 $labels 變數](#v10-alerting-overview-labels-templating-the-labels-variable)。
**列印個別標籤**
若要列印個別標籤，請使用 `index`函數搭配 `$labels`變數：
```
The host {{ index $labels "instance" }} has exceeded 80% CPU usage for the last 5 minutes
```
例如，使用標籤 提供提醒`instance=server1`，這會列印：
```
The host server1 has exceeded 80% CPU usage for the last 5 minutes
```
**注意**
如果您使用的是傳統條件，則 `$labels`不會包含查詢中的任何標籤。如需詳細資訊[，請參閱 $labels 變數](#v10-alerting-overview-labels-templating-the-labels-variable)。
**列印查詢的值**
若要列印即時查詢的值，您可以使用 `index`函數和 `$values`變數來列印其 Ref ID：
```
{{ index $values "A" }}
```
例如，假設即時查詢傳回值 81.2345，則會列印：
```
81.2345
```
若要列印範圍查詢的值，您必須先將其從時間序列縮減為具有減少表達式的即時向量。然後，您可以改為使用其 Ref ID 來列印減少表達式的結果。例如，如果減少表達式採用 A 的平均值，且具有 Ref ID B，您會寫入：
```
{{ index $values "B" }}
```
**列印查詢的人工值**
若要列印即時查詢的人類化值，請使用 `humanize`函數：
```
{{ humanize (index $values "A").Value }}
```
例如，假設即時查詢傳回值 81.2345，則會列印：
```
81.234
```
若要列印範圍查詢的人工值，您必須先將其從時間序列縮減為具有減少表達式的即時向量。然後，您可以改為使用其 Ref ID 來列印減少表達式的結果。例如，如果減少表達式採用 A 的平均值，且具有 Ref ID B，您會寫入：
```
{{ humanize (index $values "B").Value }}
```
**以百分比列印查詢的值**
若要以百分比形式列印即時查詢的值，請使用 `humanizePercentage`函數：
```
{{ humanizePercentage (index $values "A").Value }}
```
此函數預期值為介於 0 到 1 之間的十進位數字。如果值是介於 0 到 100 之間的十進位數字，您可以在查詢中或使用數學表達式將其除以 100。如果查詢是範圍查詢，您必須先將其從時間序列縮減為具有減少表達式的即時向量。
**從查詢的值設定嚴重性**
若要從查詢的值設定嚴重性標籤，請使用 if 陳述式和大於比較函數。比較`$values`文字/範本不支援類型強制時`80.0`，請務必使用小數 (`50.0`、`0.0`、 等）。您可以在[此處](https://pkg.go.dev/text/template#hdr-Functions)找到所有支援的比較函數清單。
```
{{ if (gt $values.A.Value 80.0) -}}
high
{{ else if (gt $values.A.Value 50.0) -}}
medium
{{ else -}}
low
{{- end }}
```
**從傳統條件列印所有標籤**
如果您使用傳統條件，則無法使用 從查詢`$labels`列印標籤，而且必須`$values`改用 。原因是傳統條件會捨棄這些標籤，以強制執行單維行為 （每個警示規則最多一個提醒）。如果傳統條件未捨棄這些標籤，則傳回許多時間序列的查詢會在觸發之間產生警示，並持續解決，因為標籤會在每次評估警示規則時變更。
反之，`$values`變數包含所有觸發條件的所有時間序列的減少值。例如，如果您的警示規則具有傳回兩個時間序列的查詢 A，以及具有兩個條件的傳統條件 B，則 `$values` 將包含 `B0`、 `B1``B2`和 `B3`。如果傳統條件 B 只有一個條件，則 `$values` 只會包含 `B0`和 `B1`。
若要列印所有射擊時間序列的所有標籤，請使用下列範本 （請務必使用傳統條件的 Ref ID 取代規則表達`B`式中的 )：
```
{{ range $k, $v := $values -}}
{{ if (match "B[0-9]+" $k) -}}
{{ $k }}: {{ $v.Labels }}{{ end }}
{{ end }}
```
例如，超過單一條件的兩個時間序列的傳統條件會列印：
```
B0: instance=server1
B1: instance=server2
```
如果傳統條件有兩個或多個條件，且時間序列同時超過多個條件，則會針對超過的每個條件複製其標籤：
```
B0: instance=server1
B1: instance=server2
B2: instance=server1
B3: instance=server2
```
如果您需要列印唯一標籤，建議您改為將提醒規則從單維變更為多維。您可以透過將傳統條件取代為減少和數學表達式來執行此操作。
**從傳統條件列印所有值**
若要從傳統條件列印所有值，請採用上述範例並以 `$v.Labels`取代`$v.Value`：
```
{{ range $k, $v := $values -}}
{{ if (match "B[0-9]+" $k) -}}
{{ $k }}: {{ $v.Value }}{{ end }}
{{ end }}
```
例如，超過單一條件的兩個時間序列的傳統條件會列印：
```
B0: 81.2345
B1: 84.5678
```
如果傳統條件有兩個或多個條件，且時間序列同時超過多個條件，則 `$values`將包含所有條件的值：
```
B0: 81.2345
B1: 92.3456
B2: 84.5678
B3: 95.6789
```
## Variables
在範本標籤和註釋時，您可以使用下列變數：
### 標籤變數
`$labels` 變數包含查詢中的所有標籤。例如，假設您有一個查詢會傳回所有伺服器的 CPU 用量，而且您有一個警示規則，會在您的任何伺服器在過去 5 分鐘內超過 80% 的 CPU 用量時觸發。您想要將摘要註釋新增至提醒，告知您哪個伺服器正在經歷高 CPU 使用率。您可以使用 `$labels`變數撰寫範本，列印人類可讀的句子，例如：
```
CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes
```
**注意**
如果您使用的是傳統條件，則 `$labels`不會包含查詢中的任何標籤。傳統條件會捨棄這些標籤，以強制執行單維行為 （每個警示規則最多一個警示）。如果您想要在範本中使用查詢中的標籤，請遵循先前的*列印傳統條件範例中的所有標籤*。
### 值變數
`$value` 變數是一個字串，其中包含所有即時查詢的標籤和值；閾值、減少和數學表達式，以及警示規則中的傳統條件。它不包含範圍查詢的結果，因為這些查詢可以傳回 10s 到 10，000s 的資料列或指標。如果這樣做，特別是大型查詢，單一提醒可能會使用 10 MBs 的記憶體，且 Grafana 會很快耗盡記憶體。
若要在摘要中列印`$value`變數，您會撰寫如下內容：
```
CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ $value }}
```
看起來會像這樣：
```
CPU usage for instance1 has exceeded 80% for the last 5 minutes: [ var='A' labels={instance=instance1} value=81.234 ]
```
這裡`var='A'`是指具有參考 ID A 的即時查詢，`labels={instance=instance1}`是指標籤，並`value=81.234`是指過去 5 分鐘內的平均 CPU 使用量。
如果您想要只列印部分字串而非完整字串，請使用 `$values`變數。它包含與 相同的資訊`$value`，但在結構化資料表中，並且更容易使用，然後編寫規則表達式來只符合您想要的文字。
### 值變數
`$values` 變數是包含所有即時查詢和表達式之標籤和浮點值的資料表，依其 Ref IDs 編製索引。
若要使用 Ref ID A 列印即時查詢的值：
```
CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ index $values "A" }}
```
例如，針對具有標籤的提醒`instance=server1`和具有值 的即時查詢`81.2345`，這會列印：
```
CPU usage for instance1 has exceeded 80% for the last 5 minutes: 81.2345
```
如果 Ref ID A 中的查詢是範圍查詢而非即時查詢，請使用 Ref ID B 新增減少表達式，並以 `(index $values "A")` 取代`(index $values "B")`：
```
CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ index $values "B" }}
```
## 函數
在範本化標籤和註釋時，您可以使用下列函數：
**args**
`args` 函數會將物件清單轉譯為索引鍵為 arg0、arg1 等的映射。這是為了允許將多個引數傳遞至 範本。
```
{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}}
```
```
1 2
```
**externalURL**
`externalURL` 函數會傳回 Grafana 伺服器的外部 URL。
```
{{ externalURL }}
```
```
https://example.com/grafana
```
**graphLink**
`graphLink` 函數會針對指定的表達式和資料來源，傳回 中圖形檢視[在 Grafana 第 10 版中探索](v10-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 伺服器的路徑。
```
{{ pathPrefix }}
```
```
/grafana
```
**tableLink**
`tableLink` 函數會針對指定的表達式和資料來源，傳回 中表格式檢視[在 Grafana 第 10 版中探索](v10-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
```