本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 连接 Grafana
<a name="connecting-telemetry-sources-connecting-grafana"></a>

Grafana 集成 AWS DevOps 使代理能够在事件调查期间从您的 Grafana 实例中查询指标、仪表板和警报数据。此集成遵循两个步骤的过程：Grafana的账户级注册，然后将其连接到各个代理空间。

为了提高安全性，Grafana 集成仅启用只读工具。写入工具已禁用，无法启用。这意味着代理可以查询和读取您的 Grafana 实例中的数据，但不能创建、修改或删除任何 Grafana 资源，例如仪表板、警报或注释。有关更多信息，请参阅[AWS DevOps 客户端中的安全](https://docs.aws.amazon.com/devopsagent/latest/userguide/aws-devops-agent-security.html)。

## Grafana 要求
<a name="grafana-requirements"></a>

在连接 Grafana 之前，请确保您已具备以下条件：
+ Grafana 版本 9.0 或更高版本。由于缺少 API 端点，某些功能，尤其是与数据源相关的操作，可能无法在早期版本中正常运行。
+ 可通过 HTTPS 访问的 Grafana 实例。支持公共网络和私有网络端点。通过私有网络连接，您的 Grafana 实例可以托管在没有公共互联网访问权限的 VPC 内。有关更多信息，请参阅 [连接到私人托管的工具](configuring-capabilities-for-aws-devops-agent-connecting-to-privately-hosted-tools.md)。
+ 一个 Grafana 服务账户，其访问令牌具有适当的读取权限

## 注册 Grafana（账户级别）
<a name="registering-grafana-account-level"></a>

Grafana 在账户级别注册，并在 AWS 该账户中的所有代理空间之间共享。

### 第 1 步：配置 Grafana
<a name="step-1-configure-grafana"></a>

1. 登录到 AWS 管理控制台

1. 导航到 AWS DevOps 代理控制台

1. 转到 “**能力提供者**” 页面（可从侧面导航栏访问）

1. **在 “遥**测**” **下**的 **“**可用提供商” 部分中找到 Grafana，然后单击 “注册”**

1. 在**配置 Grafana** 页面上，输入以下信息：
   + **服务名称**（必填）-仅使用字母数字字符、连字符和下划线输入 Grafana 服务器的描述性名称。例如 `my-grafana-server`。
   + **Grafana** 网址（必填）— 输入您的 Grafana 实例的完整 HTTPS 网址。例如 `https://myinstance.grafana.net`。
   + **服务账户访问令牌**（必填）— 输入 Grafana 服务账户访问令牌。代币通常以开头`glsa_`。要创建服务帐号令牌，请导航至您的 Grafana 实例，转**至管理 > 服务**帐号，创建一个具有 Viewer 角色的服务帐号，然后生成令牌。
   + **描述**（可选）-添加描述以帮助确定服务器的用途。例如 `Production Grafana server for monitoring`。

1. （可选）为组织目的向注册添加 AWS 标签。

1. 单击**下一步**

### 第 2 步：查看并提交 Grafana 注册信息
<a name="step-2-review-and-submit-grafana-registration"></a>

1. 查看所有 Grafana 配置细节

1. 单击 “**提交**” 完成注册

1. 成功注册后，Grafana 将显示在 “能力提供者” **页面的 “当前**已注册” 部分

## 将 Grafana 添加到代理空间
<a name="adding-grafana-to-an-agent-space"></a>

在账户级别注册 Grafana 后，你可以将其连接到个人代理空间：

1. 在 AWS DevOps 代理控制台中，选择您的代理空间

1. 前往 “**功能**” 选项卡

1. **在 “**遥测**” 部分，单击 “添加”**

1. 从可用提供**商**列表中选择 Grafana

1. 单击 “**保存**”

## 配置 Grafana 警报 webhook
<a name="configuring-grafana-alert-webhooks"></a>

您可以将 Grafana 配置为在警报触发时自动 AWS DevOps 触发代理调查，方法是通过 Grafana 联系点发送 webhook。有关 Webhook 身份验证方法和凭据管理的详细信息，请参阅。[通过 Webhook 调用 DevOps 代理](configuring-capabilities-for-aws-devops-agent-invoking-devops-agent-through-webhook.md)

### 步骤 1：创建自定义通知模板
<a name="step-1-create-a-custom-notification-template"></a>

在您的 Grafana 实例中，导航**到警报 > 联系方式 > 通知**模板，然后使用以下内容创建一个新模板：

```
{{ define "devops-agent-payload" }}
{
  "eventType": "incident",
  "incidentId": "{{ (index .Alerts 0).Labels.alertname }}-{{ (index .Alerts 0).Fingerprint }}",
  "action": "{{ if eq .Status "resolved" }}resolved{{ else }}created{{ end }}",
  "priority": "{{ if eq .Status "resolved" }}MEDIUM{{ else }}HIGH{{ end }}",
  "title": "{{ (index .Alerts 0).Labels.alertname }}",
  "description": "{{ (index .Alerts 0).Annotations.summary }}",
  "service": "{{ if (index .Alerts 0).Labels.job }}{{ (index .Alerts 0).Labels.job }}{{ else }}grafana{{ end }}",
  "timestamp": "{{ (index .Alerts 0).StartsAt }}",
  "data": {
    "metadata": {
      {{ range $k, $v := (index .Alerts 0).Labels }}
      "{{ $k }}": "{{ $v }}",
      {{ end }}
      "_source": "grafana"
    }
  }
}
{{ end }}
```

此模板将 Grafana 警报格式化为代理所期望的 webhook 有效载荷结构。 AWS DevOps 它将警报标签、注释和状态映射到相应的字段中，并将所有警报标签作为元数据包括在内。

**注意：**此模板仅处理群组中的第一个警报。默认情况下，Grafana 将多个触发警报分组为一个通知。要确保每个警报都是单独发送的，请将通知策略配置为按分组`alertname`。此外，此模板不会对标签值或注释中的特殊 JSON 字符进行转义。确保警报标签和`summary`注释中不包含双引号或换行符等字符，这会生成无效的 JSON。

### 第 2 步：创建 webhook 联系人
<a name="step-2-create-a-webhook-contact-point"></a>

1. **在 Grafana 中，导航**至 “警报” > “联系人”，然后单击 “添加联系人**”**

1. 选择 **Webhook** 作为集成类型

1. 将**网址**设置为你的 AWS DevOps 代理 webhook 端点

1. 在 “**可选 Webhook 设置”** 下，根据您的 Webhook 类型配置身份验证标头。有关详细信息，请参阅 [Webhook 身份验证方法](configuring-capabilities-for-aws-devops-agent-invoking-devops-agent-through-webhook.md)。

1. 将 “**消息**” 字段设置为使用您的自定义模板：`{{ template "devops-agent-payload" . }}`

1. 单击 “**保存联系人”**

### 步骤 3：将联系人分配给通知策略
<a name="step-3-assign-the-contact-point-to-a-notification-policy"></a>

1. 导航至 “**警报” > “通知策略”**

1. 编辑现有策略或创建新策略

1. 将联系点设置为您创建的 webhook 联系点

1. 点击 “**保存政策**”

当匹配的警报触发时，Grafana 会将格式化的有效负载发送 AWS DevOps 给 Agent，代理将自动开始调查。

## 限制
<a name="limitations"></a>
+ **ClickHouse 数据源工具**-目前不支持 ClickHouse 数据源工具。
+ **主动预防事件** — 目前[主动预防事故](working-with-devops-agent-proactive-incident-prevention.md)不使用 Grafana 工具。计划在 future 版本中提供支持。

### 亚马逊 Managed Grafana 注意事项
<a name="amazon-managed-grafana-considerations"></a>

如果您使用的是[亚马逊托管 Grafana](https://aws.amazon.com/grafana/) (AMG)，请注意以下限制：
+ **不支持 Webhook 联系点** — AMG 目前在其警报配置中不支持 webhook 联系点。您不能使用 AMG 直接向代理发送警报 Webhook。 AWS DevOps 有关详情，请参阅 [Amazon Managed Grafana 中的提醒联系人](https://docs.aws.amazon.com/grafana/latest/userguide/v9-alerting-explore-contacts.html)。
+ **服务账户令牌到期** — AMG 服务账户令牌的有效期最长为 30 天。在代币到期之前，您需要轮换代币并在代理 AWS DevOps 中更新您的 Grafana 注册。有关如何更新凭[据的信息，请参阅管理 Grafana](#managing-grafana-connections) 连接。有关 AMG 代币限制的详细信息，请参阅[亚马逊托管 Grafana 中的服务账户](https://docs.aws.amazon.com/grafana/latest/userguide/service-accounts.html)。

## 管理 Grafana 连接
<a name="managing-grafana-connections"></a>
+ **更新凭证**-如果您的服务帐号令牌过期或需要更新，请从 “功能提供商” 页面注销 Grafana，然后使用新令牌重新注册。
+ **查看连接的实例**-在 AWS DevOps 代理控制台中，选择您的代理空间，然后转到功能选项卡以查看连接的遥测源。
+ **移除 Grafana** **— 要断开 Grafana 与代理空间的连接，请在 “遥测” 部分将其选中，然后单击 “删除”。**要完全删除注册，请先将其从所有代理空间中删除，然后从 “能力提供者” 页面取消注册。