本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 佈建 Grafana 警示資源
<a name="v10-alerting-setup-provision"></a>

****  
本文件主題專為支援 Grafana **10.x 版的 Grafana** 工作區而設計。  
如需支援 Grafana 9.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 9 版](using-grafana-v9.md)。  
如需支援 Grafana 8.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 8 版](using-grafana-v8.md)。

警示基礎設施通常很複雜，管道的許多部分通常位於不同的位置。在多個團隊和組織中進行擴展，是一項特別具挑戰性的任務。Grafana 警示佈建可讓您以最適合您組織的方式建立、管理和維護警示資料，藉此簡化此程序。

有兩種選項可供選擇：

1. 使用警示佈建 HTTP API 佈建您的警示資源。
**注意**  
一般而言，您無法從 Grafana UI 編輯 API 佈建的提醒規則。  
若要啟用編輯，請在 API 中建立或編輯提醒規則時，將 x-disable-provenance 標頭新增至下列請求：  

   ```
   POST /api/v1/provisioning/alert-rules
   PUT /api/v1/provisioning/alert-rules/{UID}
   ```

1. 使用 Terraform 佈建提醒資源。

**注意**  
目前，佈建 Grafana 警示支援警示規則、聯絡點、靜音時間和範本。使用檔案佈建或 Terraform 佈建的提醒資源只能在建立它們的來源中編輯，而不是從 Grafana 或任何其他來源中編輯。例如，如果您使用來自磁碟的檔案佈建提醒資源，則無法編輯 Terraform 或 Grafana 中的資料。

**Topics**
+ [使用 Terraform 建立和管理提醒資源](v10-alerting-setup-provision-terraform.md)
+ [在 Grafana 中檢視佈建的提醒資源](v10-alerting-setup-provision-view.md)

# 使用 Terraform 建立和管理提醒資源
<a name="v10-alerting-setup-provision-terraform"></a>

****  
本文件主題專為支援 Grafana **10.x 版的 Grafana** 工作區而設計。  
如需支援 Grafana 9.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 9 版](using-grafana-v9.md)。  
如需支援 Grafana 8.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 8 版](using-grafana-v8.md)。

使用 Terraform 的 Grafana 提供者來管理您的提醒資源，並將它們佈建到您的 Grafana 系統。Grafana 警示的 Terraform 提供者支援可讓您輕鬆地建立、管理和維護整個 Grafana 警示堆疊作為程式碼。

如需使用 Terraform 管理提醒資源的詳細資訊，請參閱 Terraform 文件中的 [Grafana 提供者](https://registry.terraform.io/providers/grafana/grafana/latest/docs)文件。

完成下列任務，以使用 Terraform 建立和管理提醒資源。

1. 建立用於佈建的 API 金鑰。

1. 設定 Terraform 提供者。

1. 在 Terraform 中定義您的提醒資源。

1. 執行 `terraform apply` 來佈建您的提醒資源。

## 先決條件
<a name="v10-alerting-setup-provision-tf-prerequisites"></a>
+ 確保您擁有 grafana/grafana [Terraform 提供者](https://registry.terraform.io/providers/grafana/grafana/1.28.0) 1.27.0 或更高版本。
+ 確保您使用的是 Grafana 9.1 或更高版本。如果您使用 Grafana 第 9 版建立 Amazon Managed Grafana 執行個體，則這是 true。

## 建立用於佈建的 API 金鑰
<a name="v10-alerting-setup-provision-tf-apikey"></a>

您可以[建立一般 Grafana API 金鑰](Using-Grafana-APIs.md)來向 Grafana 驗證 Terraform。使用 API 金鑰的大多數現有工具應該會自動使用新的 Grafana 警示支援。如需建立金鑰以搭配 Terraform 使用的詳細資訊，請參閱[使用 Terraform for Amazon Managed Grafana 自動化](https://aws-observability.github.io/observability-best-practices/recipes/recipes/amg-automation-tf/)。

**建立用於佈建的 API 金鑰**

1. 為您的 CI 管道建立新的服務帳戶。

1. 指派角色「存取警示規則佈建 API」。

1. 建立新的服務帳戶字符。

1. 命名並儲存字符以用於 Terraform。

或者，您可以使用基本身分驗證。若要檢視所有支援的身分驗證格式，請參閱 Terraform 文件中的 [Grafana 身分驗證](https://registry.terraform.io/providers/grafana/grafana/latest/docs#authentication)。

## 設定 Terraform 提供者
<a name="v10-alerting-setup-provision-tf-configure"></a>

Grafana 警示支援包含在 [Grafana Terraform 提供者](https://registry.terraform.io/providers/grafana/grafana/latest/docs)中。

以下是可用來設定 Terraform 提供者的範例。

```
terraform {
    required_providers {
        grafana = {
            source = "grafana/grafana"
            version = ">= 1.28.2"
        }
    }
}

provider "grafana" {
    url = <YOUR_GRAFANA_URL>
    auth = <YOUR_GRAFANA_API_KEY>
}
```

## 佈建聯絡點和範本
<a name="v10-alerting-setup-provision-tf-contacts"></a>

聯絡點會將警示堆疊連線至外部世界。他們告訴 Grafana 如何連接到您的外部系統以及在何處傳送通知。有十五種不同的[整合](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/contact_point#optional)可供選擇。此範例使用 Slack 聯絡點。

**佈建聯絡點和範本**

1. 將此程式碼區塊複製到本機電腦上的 .tf 檔案。將 *<slack-webhook-url>* 取代為您的 Slack Webhook URL （或其他聯絡點詳細資訊）。

   此範例會建立將提醒通知傳送至 Slack 的聯絡點。

   ```
   resource "grafana_contact_point" "my_slack_contact_point" {
       name = "Send to My Slack Channel"
   
       slack {
           url = <slack-webhook-url>
           text = <<EOT
   {{ len .Alerts.Firing }} alerts are firing!
   
   Alert summaries:
   {{ range .Alerts.Firing }}
   {{ template "Alert Instance Template" . }}
   {{ end }}
   EOT
       }
   }
   ```

1. 在文字欄位中輸入通知的文字。

   `text` 欄位支援 [Go 樣式範本](https://pkg.go.dev/text/template)。這可讓您直接在 Terraform 中管理 Grafana 提醒通知範本。

1. 執行 `terraform apply` 命令。

1. 前往 Grafana UI 並檢查聯絡點的詳細資訊。

   您無法從 UI 編輯透過 Terraform 佈建的資源。這可確保警示堆疊始終與您的程式碼保持同步。

1. 按一下**測試**以驗證聯絡點是否正常運作。

**注意**  
您可以在許多聯絡點之間重複使用相同的範本。在上述範例中，使用 陳述式內嵌共用範本 `{{ template "Alert Instance Template" . }}`  
然後，可以在 Terraform 中單獨管理此片段：  

```
resource "grafana_message_template" "my_alert_template" {
    name = "Alert Instance Template"

    template = <<EOT
{{ define "Alert Instance Template" }}
Firing: {{ .Labels.alertname }}
Silence: {{ .SilenceURL }}
{{ end }}
EOT
}
```

## 佈建通知政策和路由
<a name="v10-alerting-setup-provision-tf-notifications"></a>

通知政策會告知 Grafana 如何路由警示執行個體，而不是路由到何處。它們使用標籤和配對器系統，將射擊提醒連接到您先前定義的聯絡點。

**佈建通知政策和路由**

1. 將此程式碼區塊複製到本機電腦上的 .tf 檔案。

   在此範例中，警示會依 分組`alertname`，這表示來自共用相同名稱之警示的任何通知都會分組為相同的 Slack 訊息。

   如果您想要以不同的方式路由特定通知，您可以新增子政策。子政策可讓您根據標籤比對，將路由套用至不同的提醒。在此範例中，我們將靜音時間套用至標籤為 a=b 的所有提醒。

   ```
   resource "grafana_notification_policy" "my_policy" {
       group_by = ["alertname"]
       contact_point = grafana_contact_point.my_slack_contact_point.name
   
       group_wait = "45s"
       group_interval = "6m"
       repeat_interval = "3h"
   
       policy {
           matcher {
               label = "a"
               match = "="
               value = "b"
           }
           group_by = ["..."]
           contact_point = grafana_contact_point.a_different_contact_point.name
           mute_timings = [grafana_mute_timing.my_mute_timing.name]
   
           policy {
               matcher {
                   label = "sublabel"
                   match = "="
                   value = "subvalue"
               }
               contact_point = grafana_contact_point.a_third_contact_point.name
               group_by = ["..."]
           }
       }
   }
   ```

1. 在互斥時間欄位中，將互斥時間連結至您的通知政策。

1. 執行 `terraform apply` 命令。

1. 前往 Grafana UI 並檢查通知政策的詳細資訊。
**注意**  
您無法從 UI 編輯從 Terraform 佈建的資源。這可確保警示堆疊始終與您的程式碼保持同步。

1. 按一下**測試**以驗證通知點是否正常運作。

## 佈建靜音計時
<a name="v10-alerting-setup-provision-tf-mutetiming"></a>

靜音計時可讓您在定義的期間內將警示通知靜音。

**佈建靜音計時**

1. 將此程式碼區塊複製到本機電腦上的 .tf 檔案。

   在此範例中，提醒通知會在週末靜音。

   ```
   resource "grafana_mute_timing" "my_mute_timing" {
       name = "My Mute Timing"
   
       intervals {
           times {
             start = "04:56"
             end = "14:17"
           }
           weekdays = ["saturday", "sunday", "tuesday:thursday"]
           months = ["january:march", "12"]
           years = ["2025:2027"]
       }
   }
   ```

1. 執行 `terraform apply` 命令。

1. 前往 Grafana UI 並檢查靜音時間的詳細資訊。

1. 使用 `mute_timings` 欄位，在通知政策中參考您新建立的靜音時間。這會將您的靜音時間套用至部分或全部通知。
**注意**  
您無法從 UI 編輯從 Terraform 佈建的資源。這可確保警示堆疊始終與您的程式碼保持同步。

1. 按一下**測試**以驗證靜音計時是否正常運作。

## 佈建提醒規則
<a name="v10-alerting-setup-provision-tf-rules"></a>

[提醒規則](v10-alerting-configure.md)可讓您針對任何 Grafana 資料來源發出提醒。這可以是您已設定的資料來源，也可以在 [Terraform 中與提醒規則一起定義資料來源](https://registry.terraform.io/providers/grafana/grafana/latest/docs/resources/data_source)。

**佈建提醒規則**

1. 建立要查詢的資料來源和要存放規則的資料夾。

   在此範例中，使用[設定 TestData 資料來源進行測試](testdata-data-source.md)資料來源。

   警示可以針對 Grafana 中的任何後端資料來源定義。

   ```
   resource "grafana_data_source" "testdata_datasource" {
       name = "TestData"
       type = "testdata"
   }
   
   resource "grafana_folder" "rule_folder" {
       title = "My Rule Folder"
   }
   ```

1. 定義提醒規則。

   如需警示規則的詳細資訊，請參閱[如何建立 Grafana 受管警示](https://grafana.com/blog/2022/08/01/grafana-alerting-video-how-to-create-alerts-in-grafana-9/)。

1. 建立包含一或多個規則的規則群組。

   在此範例中，會使用 `grafana_rule_group` 資源群組。

   ```
   resource "grafana_rule_group" "my_rule_group" {
       name = "My Alert Rules"
       folder_uid = grafana_folder.rule_folder.uid
       interval_seconds = 60
       org_id = 1
   
       rule {
           name = "My Random Walk Alert"
           condition = "C"
           for = "0s"
   
           // Query the datasource.
           data {
               ref_id = "A"
               relative_time_range {
                   from = 600
                   to = 0
               }
               datasource_uid = grafana_data_source.testdata_datasource.uid
               // `model` is a JSON blob that sends datasource-specific data.
               // It's different for every datasource. The alert's query is defined here.
               model = jsonencode({
                   intervalMs = 1000
                   maxDataPoints = 43200
                   refId = "A"
               })
           }
   
           // The query was configured to obtain data from the last 60 seconds. Let's alert on the average value of that series using a Reduce stage.
           data {
               datasource_uid = "__expr__"
               // You can also create a rule in the UI, then GET that rule to obtain the JSON.
               // This can be helpful when using more complex reduce expressions.
               model = <<EOT
   {"conditions":[{"evaluator":{"params":[0,0],"type":"gt"},"operator":{"type":"and"},"query":{"params":["A"]},"reducer":{"params":[],"type":"last"},"type":"avg"}],"datasource":{"name":"Expression","type":"__expr__","uid":"__expr__"},"expression":"A","hide":false,"intervalMs":1000,"maxDataPoints":43200,"reducer":"last","refId":"B","type":"reduce"}
   EOT
               ref_id = "B"
               relative_time_range {
                   from = 0
                   to = 0
               }
           }
   
           // Now, let's use a math expression as our threshold.
           // We want to alert when the value of stage "B" above exceeds 70.
           data {
               datasource_uid = "__expr__"
               ref_id = "C"
               relative_time_range {
                   from = 0
                   to = 0
               }
               model = jsonencode({
                   expression = "$B > 70"
                   type = "math"
                   refId = "C"
               })
           }
       }
   }
   ```

1. 前往 Grafana UI 並檢查您的提醒規則。

   您可以查看警示規則是否正在觸發。您也可以查看每個警示規則查詢階段的視覺化。

   當警示觸發時，Grafana 會透過您定義的政策路由通知。

   例如，如果您選擇 Slack 做為聯絡窗口，Grafana 的內嵌 [Alertmanager](https://github.com/prometheus/alertmanager) 會自動將訊息發佈到 Slack。

# 在 Grafana 中檢視佈建的提醒資源
<a name="v10-alerting-setup-provision-view"></a>

****  
本文件主題專為支援 Grafana **10.x 版的 Grafana** 工作區而設計。  
如需支援 Grafana 9.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 9 版](using-grafana-v9.md)。  
如需支援 Grafana 8.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 8 版](using-grafana-v8.md)。

您可以驗證警示資源是否已在 Grafana 中建立。

**在 Grafana 中檢視佈建的資源**

1. 開啟您的 Grafana 執行個體。

1. 導覽至警示。

1. 按一下提醒資源資料夾，例如提醒規則。

   佈建的資源會標記為**佈建**，因此很清楚它們不是手動建立的。

**注意**  
您無法從 Grafana 編輯佈建的資源。您只能透過變更佈建檔案並重新啟動 Grafana 或執行熱重新載入來變更資源屬性。這可防止對資源進行變更，如果再次佈建檔案或執行熱重新載入，則會覆寫該資源。