---
title: Grafana 集成 - 实时基础设施监控告警
sidebarTitle: Grafana
description: 将 Grafana 告警与 Echobell 集成以获取即时基础设施监控通知的完整指南。包含分步设置、告警模板、webhook 配置和 Grafana 告警最佳实践。
---

import { Step, Steps } from "fumadocs-ui/components/steps";

# Grafana 集成

Grafana 是一个流行的开源分析和监控解决方案，被数千家组织用于可视化指标、日志和追踪数据。通过将 Grafana 与 Echobell 集成，您可以在指标触发警报时收到即时通知——无论是 CPU 使用率过高、内存压力、服务故障还是任何其他被监控的状态。

本综合指南将引导您完成 Grafana 与 Echobell 的警报设置，从基本配置到高级警报管理策略。

## 前提条件

开始之前，请确保您具备：

- 一个已创建至少一个频道的 Echobell 账户（[从这里开始](/zh/docs)）
- 可访问 Grafana 实例（推荐 8.0 或更高版本，9.0+ 版本兼容性最佳）
- 在 Grafana 中配置警报通知的管理权限（通常需要 Admin 或 Editor 角色）
- 对 Grafana 仪表板和指标的基本了解
- 熟悉您的监控基础设施和警报需求

## 设置概述

集成过程包含五个主要步骤，通常需要 10-15 分钟完成：

1. **创建 Echobell 频道** - 为 Grafana 警报设置专用频道
2. **配置通知模板** - 设计警报在设备上的显示方式
3. **获取 Webhook URL** - 获取频道的唯一 webhook 端点
4. **设置 Grafana 联系点** - 配置 Grafana 向 Echobell 发送警报
5. **在 Grafana 中创建警报规则** - 定义触发通知的条件

配置完成后，警报将自动实时从 Grafana 流向您的设备。

## 分步指南

<Steps>
<Step>
### 创建 Echobell 频道

1. 打开 Echobell 应用
2. 创建新频道（例如，"Grafana 警报"）
3. 选择醒目的颜色以便识别
</Step>
<Step>

### 配置通知模板

设置能有效格式化 Grafana 警报的模板：

**标题模板：**

```
{{alertName}} - {{status}}
```

**正文模板：**

```
🔔 警报：{{alertName}}
📊 指标：{{metric}}
📈 数值：{{value}}
⏰ 时间：{{time}}
ℹ️ 消息：{{message}}
```

这些模板将适用于 Grafana 的警报数据结构。

</Step>
<Step>
### 获取 Webhook URL

1. 在频道设置中，找到 **触发器** 部分
2. 复制提供的 webhook URL
3. 确保安全保管此 URL，因为它将用于 Grafana 的配置
</Step>
<Step>

### 配置 Grafana 联系点

1. 在 Grafana 中，进入 **警报** → **联系点**
2. 点击 **新建联系点**
3. 设置以下内容：
   - 名称："Echobell"
   - 类型："Webhook"
   - URL：您的 Echobell webhook URL
   - HTTP 方法：POST
   - 内容类型：application/json
4. 配置消息模板：

```json
{
  "alertName": "{{ .alertName }}",
  "status": "{{ .status }}",
  "metric": "{{ .metric }}",
  "value": "{{ .value }}",
  "time": "{{ .time }}",
  "message": "{{ .message }}",
  "externalLink": "{{ .dashboardURL }}"
}
```

</Step>
<Step>
### 创建警报规则

1. 导航至 **警报** → **警报规则**
2. 创建新警报规则或编辑现有规则
3. 在规则配置中：
   - 为指标设置适当的条件
   - 选择 "Echobell" 联系点
   - 配置警报评估标准
</Step>
</Steps>

## 测试集成

要验证您的设置：

1. 创建一个能快速触发的测试警报规则
2. 等待条件满足
3. 检查 Echobell 应用中的警报通知
4. 验证所有警报变量是否正确显示
5. 点击通知以访问链接的 Grafana 仪表板

## 警报通知类型

在订阅 Grafana 警报频道时，配置这些关键通知类型：

- 将 **时效性** 用于紧急关键系统警报和紧急通知
- 将 **通话** 用于严重故障、临界值突破或紧急警报
- 将 **普通** 用于标准信息警报和常规通知

## 警报管理最佳实践

### 警报模板组织

**在所有频道中保持警报模板清晰一致：**

```
标题：{{alertName}} - {{status}}
正文：
服务器：{{instance}}
指标：{{metric}}
当前值：{{value}}
阈值：{{threshold}}
```

- **使用结构化格式** - 用清晰的标签组织信息
- **包含关键信息** - 指标名称、数值、阈值、受影响的系统
- **适度使用表情符号** - 🚨 用于严重、⚠️ 用于警告、✅ 用于已解决
- **保持标题简洁** - 目标是 5-8 个词，能立即传达问题
- **测试模板** - 在部署前发送测试警报验证格式

### 关键警报配置

**设置适当的警报阈值以避免通知疲劳：**

- **避免过度警报** - 将阈值设置在可操作的级别，而不是"有趣"的级别
- **使用滞后设置** - 为警报和恢复配置不同的阈值
- **分组相关警报** - 将相关条件合并到单个警报规则中
- **设置适当的评估间隔** - 在响应速度和噪音减少之间取得平衡
- **考虑时间窗口** - 在警报前使用多次条件检查

**阈值策略示例：**

```
# 不好：CPU 50% 时警报（过于敏感）
cpu_usage > 50

# 较好：5 分钟内 80% 时警报
avg_over_time(cpu_usage[5m]) > 80

# 最佳：渐进式警报
# 70% 持续时警告，90% 时严重
```

### 使用有意义的警报名称

给警报起描述性的名称，立即传达：

- **什么** 被监控（CPU、内存、磁盘）
- **在哪里** 发生（生产环境、测试环境、特定实例）
- **为什么** 重要（面向用户的服务、关键数据库）

好的示例：

- "生产数据库 - 连接池使用率过高"
- "API 网关 - 响应时间下降"
- "工作节点 3 - 磁盘空间严重不足"

避免：

- "警报 1"、"测试警报"、"CPU 高"

### 包含足够的上下文

您的警报消息应该回答：

- **发生了什么？** 触发的具体条件
- **在哪里？** 哪个系统、服务或实例
- **有多严重？** 当前值 vs 阈值
- **什么时候？** 警报的时间戳
- **下一步？** 相关仪表板或运维手册的链接

### 配置优先级级别

策略性地使用 Echobell 的[通知类型](/zh/docs/notification)：

- **普通**：信息警报、已解决通知、非紧急警告
- **时效性**：需要在数小时内关注的重要警报
- **通话**：需要立即响应的关键生产问题

将 Grafana 严重级别映射到通知类型：

```
严重 + 生产 → 通话
高 + 生产 → 时效性
中 → 时效性
低 → 普通
信息/已解决 → 普通
```

### 警报安全

**保护您的监控基础设施：**

- **保密 webhook URL** - 它们提供未经身份验证的通知发送访问权限
- **使用环境变量** - 不要在 Grafana 配置文件中硬编码 URL
- **定期轮换 webhook** - 特别是当团队成员离开时
- **监控 webhook 投递** - 跟踪失败的投递并调查异常
- **审核警报配置** - 定期检查谁有权限修改警报
- **验证警报来源** - 为联系点使用 Grafana 的内置身份验证

### 警报生命周期管理

**保持健康的警报管理习惯：**

1. **定期审查** - 每季度审核警报以删除过时规则
2. **记录警报** - 添加说明解释每个警报存在的原因
3. **跟踪警报历史** - 监控哪些警报最频繁触发
4. **调整阈值** - 根据历史数据和误报率进行调整
5. **归档旧警报** - 对于即将退役的服务，禁用但保留规则
6. **版本控制** - 使用 Grafana 配置来跟踪警报变更

### 性能考虑

- **避免警报风暴** - 配置适当的分组和时间
- **使用通知策略** - 将不同严重级别路由到适当的频道
- **设置等待/重复间隔** - 防止重复通知
- **分组相似警报** - 通过聚合减少通知量
- **考虑时间段** - 使用[条件](/zh/docs/conditions)进行工作时间过滤

## 实际示例

### 高 CPU 警报

```
标题：{{instance}} CPU 严重
正文：CPU 使用率：{{cpu_percent}}%
持续时间：{{duration}}
时间：{{time}}
仪表板：{{dashboard_url}}
```

### 内存压力

```
标题：内存警告 - {{hostname}}
正文：可用：{{available_mb}}MB ({{percent_free}}%)
阈值：{{threshold_mb}}MB
操作：检查内存密集型进程
```

### 服务宕机

```
标题：🚨 {{service_name}} 不可达
正文：健康检查失败
上次成功：{{last_successful_check}}
影响：{{affected_users}} 用户受影响
运维手册：{{runbook_url}}
```

## 常见用例

### 基础设施监控

- CPU、内存、磁盘使用率阈值
- 网络吞吐量和丢包
- 服务可用性和健康检查
- 容器和 Pod 状态监控

### 应用性能

- 响应时间下降
- 错误率上升
- 数据库连接池耗尽
- 队列深度和处理延迟

### 业务指标

- 交易量异常
- 每分钟收入下降
- 活跃用户数变化
- API 速率限制接近

### 安全监控

- 身份验证失败尝试
- 异常访问模式
- 证书过期警告
- 防火墙规则违规

在我们的[关于 Grafana 通话通知的博客文章](/blog/grafana-call-notification)中了解更多集成策略。

## 故障排除

如果您没有收到警报，请按以下诊断步骤操作：

### Webhook 未触发通知

1. **验证 webhook URL 是否正确复制**

   - 进入 Echobell 频道 → 触发器 → Webhook
   - 复制包含 `https://hook.echobell.one/t/` 的完整 URL
   - 确保粘贴到 Grafana 时没有添加额外的空格或字符

2. **检查频道是否处于活动状态**

   - 打开 Echobell 应用
   - 导航到您的 Grafana 警报频道
   - 确认它没有被意外删除或归档

3. **确保有活跃订阅者**

   - 至少需要一个人订阅才能接收通知
   - 检查频道的订阅者列表
   - 确认您的个人订阅处于活动状态

4. **验证 Grafana 联系点配置**

   - 在 Grafana 中进入 Alerting → Contact points
   - 打开您的 Echobell 联系点
   - 确认 URL 与您频道的 webhook 匹配
   - 检查 HTTP 方法是否设置为 POST
   - 确认 Content-Type 是 application/json

5. **检查 Grafana 警报规则配置**

   - 导航到 Alerting → Alert rules
   - 打开应该触发的特定规则
   - 确认规则已链接到您的 Echobell 联系点
   - 检查通知策略是否路由到正确的联系点

6. **查看 Grafana 的警报历史**
   - 进入 Alerting → Alert rules
   - 点击您的规则 → 显示历史
   - 验证警报是否实际触发（不是处于待定状态）
   - 检查是否有任何评估错误

### 警报触发但未送达

1. **直接测试 webhook**

   ```bash
   curl -X POST https://hook.echobell.one/t/YOUR_TOKEN \
     -H "Content-Type: application/json" \
     -d '{"alertName": "Test", "status": "firing"}'
   ```

   如果您从此收到通知但未从 Grafana 收到，问题出在 Grafana 的配置上。

2. **检查 Grafana 的通知策略**

   - 进入 Alerting → Notification policies
   - 验证您规则的标签是否与策略路由规则匹配
   - 检查时间问题（分组等待时间、重复间隔）

3. **查看 Grafana 日志**
   - 在 Grafana 日志中查找 webhook 投递错误
   - 检查 HTTP 状态码（应该是 200）
   - 调查任何超时或连接错误

### 通知渲染不正确

1. **模板变量与 Grafana 的负载不匹配**

   - Grafana 发送特定字段名称如 `.alertName`、`.status` 等
   - 确保您的模板变量与负载结构匹配
   - 使用 Grafana 的"测试"按钮查看实际负载

2. **通知中缺少信息**

   - 根据警报配置，某些 Grafana 变量可能为空
   - 在模板中添加回退值：`{{alertName || "未知警报"}}`
   - 查看 Grafana 文档了解可用的模板变量

3. **JSON 解析错误**
   - 验证 Grafana 的消息模板是有效的 JSON
   - 检查未转义的引号或特殊字符
   - 使用在线 JSON 验证器验证负载结构

### 警报时间问题

1. **接收警报延迟**

   - 检查您的网络连接
   - 确认 Grafana 可以访问 Echobell 的服务器
   - 检查 Grafana 的评估间隔（可能导致延迟）
   - 检查通知策略的时间设置

2. **重复通知**

   - 检查通知策略中的重复间隔设置
   - 检查是否有多个规则为同一条件触发
   - 确认频道只配置了一个联系点

3. **安静时段的通知**
   - iOS 专注模式可能影响通知投递
   - 时效性和通话通知可以绕过某些专注模式
   - 检查您设备的通知设置

## 隐私和数据处理

Echobell 的隐私优先方案意味着：

- 警报内容本地存储在您的设备上
- 仅在服务器上存储基本配置数据
- Webhook URL 应被视为机密
- Echobell 服务器不保留警报数据

## 其他资源

- [Grafana 警报文档](https://grafana.com/docs/grafana/latest/alerting/)
- [Echobell Webhook 集成](/zh/docs/webhook)
- [通知模板指南](/zh/docs/notification)
- [支持中心](/zh/docs/support)