本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 標籤和註釋
****
本文件主題專為支援 Grafana **9.x 版的 Grafana** 工作區而設計。
如需支援 Grafana 10.x 版的 Grafana 工作區，請參閱[使用 Grafana 第 10 版](using-grafana-v10.md)。
如需支援 Grafana 8.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 8 版](using-grafana-v8.md)。
標籤和註釋包含提醒的相關資訊。標籤和註釋的結構都相同：一組具名值，但其預期用途不同。標籤或同等註釋的範例可能是 `alertname="test"`。
標籤和註釋的主要區別在於，標籤用於區分提醒與所有其他提醒，而註釋用於將其他資訊新增至現有提醒。
例如，請考慮兩個高 CPU 警示：一個用於 `server1`，另一個用於 `server2`。在此範例中，我們可能會有一個名為 的標籤，`server`其中第一個提醒具有 標籤`server="server1"`，而第二個提醒具有 標籤`server="server2"`。不過，我們也可能想要將描述新增至每個提醒，例如 `"The CPU usage for server1 is above 75%."`，其中 `server1`和 `75%` 會取代為伺服器的名稱和 CPU 使用量 （有關如何執行此操作，請參閱 [範本標籤和註釋](v9-alerting-explore-labels-templating.md)上的文件）。這種描述會更適合做為註釋。
## 標籤
標籤包含識別提醒的資訊。標籤的範例可能是 `server=server1`。每個提醒可以有多個標籤，且提醒的完整標籤集稱為其標籤集。這是識別提醒的標籤集。
例如，提醒可能已設定標籤，`{alertname="High CPU usage",server="server1"}`而另一個提醒可能已設定標籤`{alertname="High CPU usage",server="server2"}`。這些是兩個單獨的提醒，因為雖然其`alertname`標籤相同，但其`server`標籤不同。
警示的標籤集是資料來源的標籤、警示規則的自訂標籤，以及許多預留標籤的組合，例如 `alertname`。
**自訂標籤**
自訂標籤是來自提醒規則的其他標籤。如同註釋，自訂標籤必須具有名稱，而且其值可以包含文字和範本程式碼的組合，在觸發提醒時進行評估。您可以[在這裡](v9-alerting-explore-labels-templating.md)找到如何範本自訂標籤的文件。
搭配 範本使用自訂標籤時，請務必確保標籤值不會在警示規則的連續評估之間變更，因為這最終會產生大量不同的警示。不過，範本可以為不同的提醒產生不同的標籤值。例如，請勿將查詢的值放在自訂標籤中，因為這最終會在每次值變更時建立新的一組提醒。請改用註釋。
也請務必確保警示的標籤集沒有兩個或多個具有相同名稱的標籤。如果自訂標籤的名稱與資料來源的標籤相同，則會取代該標籤。不過，如果自訂標籤與預留標籤的名稱相同，則會從提醒中省略自訂標籤。
## 註釋
註釋是將其他資訊新增至現有提醒的命名配對。Grafana 中有許多建議的註釋，例如 `description`、`runbook_url`、 `summary``dashboardUId`和 `panelId`。與自訂標籤一樣，註釋必須具有名稱，而且其值可以包含觸發提醒時評估的文字和範本程式碼組合。如果註釋包含範本程式碼，則會在觸發提醒時評估範本一次。即使警示已解決，也不會重新評估。您可以在[此處](v9-alerting-explore-labels-templating.md)找到如何建立註釋範本的文件。
# 標籤比對的運作方式
****
本文件主題專為支援 Grafana **9.x 版的 Grafana** 工作區而設計。
如需支援 Grafana 10.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 10 版](using-grafana-v10.md)。
如需支援 Grafana 8.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 8 版](using-grafana-v8.md)。
使用標籤和標籤比對器，將警示規則連結至通知政策和靜音。這可讓 以非常靈活的方式管理您的提醒執行個體、指定哪些政策應處理它們，以及哪些提醒靜音。
標籤比對器包含 3 個不同的部分：**標籤**、**值**和**運算子**。
+ Label **** 欄位是要比對的標籤名稱。它必須完全符合標籤名稱。
+ **值**欄位符合指定**標籤**名稱的對應值。比對方式取決於**運算子**值。
+ **運算**子欄位是要比對標籤值的運算子。可用的運算子包括：
| 運算子 | Description |
| --- | --- |
| `=` | 選取完全等於 值的標籤。 |
| `!=` | 選取不等於 值的標籤。 |
| `=~` | 選取 regex 符合值的標籤。 |
| `!~` | 選取不與值 regex 相符的標籤。 |
如果您使用多個標籤比對器，則會使用 AND 邏輯運算子來合併它們。這表示所有配對器都必須相符，才能將規則連結至政策。
**範例藍本**
如果您為提醒定義下列一組標籤：
```
{ foo=bar, baz=qux, id=12 }
```
然後：
+ 定義為 的標籤比對器`foo=bar`符合此提醒規則。
+ 定義為 的標籤比對器`foo!=bar`*不符合*此提醒規則。
+ 定義為 的標籤比對器`id=~[0-9]+`符合此提醒規則。
+ 定義為 的標籤比對器`baz!~[0-9]+`符合此提醒規則。
+ 定義為 `foo=bar`且`id=~[0-9]+`符合此提醒規則的兩個標籤比對程式。
# Grafana 警示中的標籤
****
本文件主題專為支援 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 提醒中唯一識別提醒的內容。
+ Alertmanager 使用標籤來比對通知政策中靜音和警示群組的警示。
+ 警示 UI 會顯示評估該規則期間產生之每個警示執行個體的標籤。
+ 聯絡點可以存取標籤，動態產生通知，其中包含導致通知的提醒特定資訊。
+ 您可以將標籤新增至[提醒規則](v9-alerting-managerules.md)。標籤可手動設定、使用範本函數，並可參考其他標籤。新增至提醒規則的標籤優先於標籤之間發生衝突的情況 (Grafana 預留標籤的情況除外，如需詳細資訊，請參閱以下內容）。
**外部警示管理員相容性**
Grafana 的內建 Alertmanager 支援 Unicode 標籤索引鍵和值。如果您使用的是外部 Prometheus Alertmanager，標籤金鑰必須與其[資料模型](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels)相容。這表示標籤索引鍵只能包含 **ASCII 字母**、**數字**以及**底線**，並與 regex 相符`[a-zA-Z_][a-zA-Z0-9_]*`。任何無效的字元都會由 Grafana 提醒引擎移除或取代，然後再根據下列規則傳送至外部 Alertmanager：
+ `Whitespace` 將會移除。
+ `ASCII characters` 將取代為 `_`。
+ `All other characters` 將以小寫十六進位表示法取代。如果這是第一個字元，則會在字首加上 `_`。
**注意**
如果多個標籤索引鍵已淨化為相同的值，則重複項目的原始標籤的短雜湊會附加為尾碼。
**Grafana 預留標籤**
**注意**
Grafana `grafana_`會保留字首為 的標籤以供特殊使用。如果從 開始新增手動設定的標籤`grafana_`，則在發生碰撞時可以覆寫。
Grafana 預留標籤的使用方式與手動設定的標籤相同。目前可用的預留標籤清單如下：
| 標籤 | Description |
| --- | --- |
| grafana\$1folder | 包含提醒的資料夾標題。 |
# 範本標籤和註釋
****
本文件主題專為支援 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
```