> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 使用 ClickStack 的告警
> 使用 ClickStack 的告警
export const Image = ({img, alt, size}) => {
return
;
};
ClickStack 内置告警支持，使团队能够针对日志、指标和链路追踪中的问题进行实时检测和响应。
可以直接在 HyperDX 界面中创建告警，并与 Slack、PagerDuty 等常见通知系统集成。
告警功能可在整个 ClickStack 数据范围内无缝运行，帮助你跟踪系统健康状况、发现性能回退，并监控关键业务事件。
## 告警类型
ClickStack 支持两种互补的告警创建方式：**搜索告警**和**仪表板图表告警**。告警创建后，会关联到相应的搜索或图表。
### 1. 搜索告警
搜索告警可让你根据已保存搜索的结果触发通知，帮助你发现特定事件或模式的出现频率是否高于 (或低于) 预期。
当定义的时间窗口内匹配结果的计数超过或低于指定阈值时，就会触发告警。
要创建搜索告警：
要为某个搜索创建告警，必须先保存该搜索。你既可以为现有的已保存搜索创建告警，也可以在创建告警的过程中保存搜索。在下面的示例中，我们假设该搜索尚未保存。
#### 打开告警创建对话框
首先输入一个[搜索](/zh/clickstack/features/search)，然后点击`搜索`页面右上角的 `Alerts` 按钮。
#### 创建告警
在告警创建面板中，你可以：
* 为与该告警关联的已保存搜索指定名称。
* 设置阈值，并指定在给定周期内达到该阈值多少次。阈值也可作为上限或下限。这里的周期还将决定告警触发的频率。
* 指定一个 `grouped by` 值。这样可按某个字段对搜索进行聚合，例如 `ServiceName`，从而基于同一个搜索触发多个告警。
* 为通知选择一个 webhook 目标端。你也可以直接在此视图中添加新的 webhook。详情请参见[添加 webhook](#add-webhook)。
保存前，ClickStack 会将阈值条件可视化，方便你确认其行为符合预期。
请注意，一个搜索可以添加多个告警。如果重复上述流程，你会在编辑告警对话框顶部看到当前告警以选项卡形式显示，并且每个告警都会分配一个编号。
### 2. 仪表板图表告警
仪表板图表告警将告警功能扩展到了图表。
你可以直接从已保存的仪表板创建基于图表的告警，并借助完整的 SQL 聚合和 ClickHouse 函数进行高级计算。
当某项指标超过设定阈值时，告警会自动触发，帮助你持续监控 KPI、延迟或其他关键指标的变化。
要为仪表板上的可视化创建告警，必须先保存该仪表板。
要添加仪表板告警：
告警可以在创建图表时创建，也可以在将图表添加到仪表板时创建，或直接添加到现有图表。在下面的示例中，我们假设该图表已存在于仪表板中。
#### 打开图表编辑对话框
打开图表的配置菜单，然后选择告警按钮。此时会显示图表编辑对话框。
#### 添加告警
选择 **Add Alert**。
#### 定义告警条件
定义条件 (`>=`、`>`、`<=`、`<`、`=`、`!=`、`<= x >=`、`> or <`) 、阈值、持续时间和 webhook。这里的持续时间也会决定告警的触发频率。
你可以直接在此视图中添加新的 webhook。详见[添加 webhook](#add-webhook)。
## 添加 webhook
在创建告警时，您既可以使用现有的 webhook，也可以新建一个。创建后，该 webhook 还可在其他告警中复用。
您可以为不同的服务类型创建 webhook，包括 Slack、PagerDuty 以及通用目标。
例如，在下方图表的告警创建过程中，在指定 webhook 之前，用户可以选择 `Add New Webhook`。
这会打开 webhook 创建对话框，您可以在其中创建新的 webhook：
webhook 名称为必填项，描述为可选项。其他需要填写的设置取决于服务类型。
请注意，ClickStack 开源版与 ClickStack Cloud 提供的服务类型有所不同。请参阅[服务类型集成](#integrations)。
### 服务类型集成
ClickStack 告警可开箱即用地集成以下服务类型：
* **Slack**：通过 webhook 或 API 直接向频道发送通知。
* **PagerDuty**：通过 PagerDuty API 将事件路由给值班团队。
* **Webhook**：通过通用 webhook 将告警连接到任何自定义系统或工作流。
**仅 ClickHouse Cloud 支持的集成**
Slack API 和 PagerDuty 集成仅在 ClickHouse Cloud 中受支持。
根据服务类型的不同，您需要提供不同的信息。具体如下：
**Slack (Webhook URL) **
* Webhook URL。例如：`https://hooks.slack.com/services/`。更多详情请参阅 [Slack 文档](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/)。
**Slack (API) **
* Slack bot token。更多详情请参阅 [Slack 文档](https://docs.slack.dev/authentication/tokens/#bot/)。
**PagerDuty API**
* PagerDuty 集成密钥。更多详情请参阅 [PagerDuty 文档](https://support.pagerduty.com/main/docs/api-access-keys)。
**Generic**
* Webhook URL
* Webhook 请求头 (可选)
* Webhook 请求体 (可选) 。请求体当前支持模板变量 `{{title}}`、`{{body}}` 和 `{{link}}`。
## 管理告警
可以通过 HyperDX 左侧的告警面板集中管理告警。
在此视图中，你可以看到所有已创建且当前在 ClickStack 中运行的告警。
此视图还会显示告警的评估历史。告警会按照固定的时间间隔重复评估 (该间隔由创建告警时设置的周期/时长决定) 。在每次评估期间，HyperDX 都会查询你的数据，以检查是否满足告警条件：
* **红条**：本次评估满足了阈值条件，告警已触发 (已发送通知)
* **绿条**：告警已完成评估，但未满足阈值条件 (未发送通知)
每次评估都是独立的——告警会检查该时间窗口内的数据，并且只有在该时刻条件为 true 时才会触发。
在上面的示例中，第一个告警在每次评估时都会触发，表明问题持续存在。第二个告警则表示问题已解决——它最初触发了两次 (红条) ，随后在后续评估中不再满足阈值条件 (绿条) 。
点击某个告警会带你进入该告警所关联的图表或搜索页面。
### 删除告警
要删除告警，请打开关联搜索或图表的编辑对话框，然后选择 **Remove Alert**。
在下面的示例中，`Remove Alert` 按钮会删除该图表上的告警。
## 基于 SQL 的图表告警
基于 SQL 的图表告警允许你编写任意 ClickHouse SQL 来定义告警条件。这样你就能完全控制过滤、聚合和计算——凡是能够用 SQL 表达的内容，都可以设置为告警。
### 支持的图表类型
基于 SQL 的告警支持以下三种图表类型：
| 图表类型 | 行为 |
| --------- | --------------------------------------- |
| **折线图** | 时间序列告警。查询必须生成按时间分桶的结果行。每个桶都会分别对照阈值进行评估。 |
| **堆叠条形图** | 时间序列告警。行为与折线图相同。 |
| **数值** | 单值告警。查询返回单个数值结果，并在每次评估时与阈值比较一次。 |
其他基于 SQL 的图表类型 (表、饼图、热力图等) 不支持告警。
### 创建 SQL 告警
要为基于 SQL 的图表创建告警：
#### 在仪表板中创建或打开基于 SQL 的图表
在已保存的仪表板中，你可以[使用 **SQL** 图表模式创建新图表](/zh/clickstack/features/dashboards/sql-visualizations)，也可以打开现有的基于 SQL 的图表进行编辑。
选择 **折线图**、**堆叠条形图** 或 **数值** 作为显示类型。
#### 添加告警
在图表编辑器的告警部分中，选择 **Add Alert**。配置以下内容：
* **阈值类型**：`>=` (大于等于) 、`>` (大于) 、`<=` (小于等于) 、`<` (小于) 、`=` (等于) 、`!=` (不等于) 、`<= x >=` (介于两者之间) 或 `> or <` (超出范围)
* **阈值**：用于比较的数值
* **间隔**：告警的评估频率 (1m、5m、15m、30m、1h、6h、12h 或 1d) 。这也定义了每次评估的时间窗口。
* **Webhook**：告警触发时使用的通知通道。请参阅[添加 webhook](#add-webhook)。
**告警时间范围**
通常，告警查询会每个间隔执行一次。但是，如果由于错误或查询过慢而跳过了一个或多个间隔，则下一次执行时会使用包含这些遗漏间隔在内的时间范围。在这种情况下，查询的 interval 参数仍会设置为告警配置的周期，但 time range 参数会反映更长的时间范围。
#### 保存仪表板
保存仪表板以激活告警。告警将按照配置的间隔开始评估。
### 如何解读查询结果
告警系统会检查 SQL 查询返回的列，以确定应将哪个值与阈值进行比较。
* **值列**：`SELECT` 子句中的**最后一个数值列**会被用作告警值。如果查询返回多个数值列 (例如 `count, avg_latency, p99_latency`) ，则只有最后一列 (`p99_latency`) 会与阈值比较。
* **时间戳列**：对于时间序列图表 (折线图 和 堆叠条形图) ，系统会将结果中的 Date/DateTime 列识别为时间桶 (即时间序列图表的 x 轴) 。系统会针对每个时间桶分别评估其值列是否超过阈值；如果任意时间桶的值突破已配置的阈值，就会触发告警。
* **分组列**：任何非数值、非时间戳列 (例如 `ServiceName`、`Environment`) 都会被视为分组维度。存在分组时，系统会分别跟踪每个唯一的分组值组合，并单独触发告警。对于每个值超过已配置阈值的分组，ClickStack 都会发送一条告警。分组仅适用于时间序列图表。
### 查询参数和宏
SQL 告警查询支持模板参数和宏，它们会在评估时自动替换。这些参数和宏与[构建基于 SQL 的图表](/zh/clickstack/features/dashboards/sql-visualizations)时可用的完全相同。
#### 必需参数与推荐参数
用于折线图或堆叠条形图告警的查询**必须**包含时间间隔参数或宏 (`{intervalSeconds:Int64}`、`{intervalMilliseconds:Int64}`、`$__timeInterval(col)` 或 `$__timeInterval_ms(col)`) 。告警执行时，该参数会被替换为告警配置的周期。
用于告警的查询**应当**包含时间范围过滤器 (`{startDateMilliseconds:Int64}` 和 `{endDateMilliseconds:Int64}`，或 `$__timeFilter(col)` 等) 。无论查询中是否包含时间范围过滤器，告警查询都会基于告警配置的周期运行。如果没有时间范围过滤器，则查询每次执行时都会读取源表中当前可用的整个时间范围。
**告警时间范围**
通常，告警查询会按每个时间间隔执行一次。但是，如果由于错误或查询过慢而跳过了一个或多个时间间隔，下一次执行时使用的时间范围将包含这些遗漏的时间间隔。在这种情况下，查询中的时间间隔参数仍会设置为告警配置的周期，但时间范围参数则会反映这一更长的时间范围。
### 告警查询示例
#### 每个服务的错误率 (时间序列)
当任一服务的错误率超过 5% 时触发告警；为避免低流量服务产生噪声告警，告警周期内的请求数至少需达到 10 个。
```sql theme={null}
WITH error_rates AS (
SELECT
$__timeInterval(Timestamp) as ts,
ServiceName,
countIf (SpanKind = 'Server') as request_count,
countIf (
SpanKind = 'Server'
and StatusCode = 'Error'
) as error_count,
error_count / request_count * 100 AS error_percent
FROM $__sourceTable
WHERE $__timeFilter(Timestamp)
GROUP BY ts, ServiceName
)
SELECT ts, ServiceName, error_percent
FROM error_rates
WHERE request_count > 10
```
**显示类型**: 折线图或堆叠条形图
**阈值**: `>= 5` (错误率达到 5% 时触发)
在此查询中，`ServiceName` 是一个非数值、非时间戳列，因此每个服务都会被作为独立的告警组进行跟踪。告警会针对每个服务分别独立触发。
#### 使用滞后平均值进行异常检测 (时间序列)
对超出滚动平均值两个标准差以上的错误计数设置告警。这有助于捕捉相对于近期基线行为的突增，而不是依赖固定阈值。
```sql theme={null}
WITH buckets AS (
SELECT
$__timeInterval(Timestamp) AS ts,
count() AS bucket_count
FROM $__sourceTable
WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
- toIntervalSecond($__interval_s * 30) -- 向前拉取 30 个时间间隔
AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
AND SeverityText = 'error'
GROUP BY ts
ORDER BY ts
WITH FILL
FROM toDateTime(fromUnixTimestamp64Milli({startDateMilliseconds:Int64}))
TO toDateTime(fromUnixTimestamp64Milli({endDateMilliseconds:Int64}))
STEP toIntervalSecond($__interval_s)
),
anomaly_detection AS (
SELECT
ts,
bucket_count,
avg(bucket_count) OVER (
ORDER BY ts ROWS BETWEEN 30 PRECEDING AND 1 PRECEDING
) AS previous_30_avg,
stddevPop(bucket_count) OVER (
ORDER BY ts ROWS BETWEEN 30 PRECEDING AND 1 PRECEDING
) AS previous_30_stddev,
greatest(
bucket_count - (previous_30_avg + 2 * previous_30_stddev), 0
) AS excess_error_count
FROM buckets
)
SELECT ts, excess_error_count
FROM anomaly_detection
WHERE ts >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
AND ts < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
```
**显示类型**：折线图
**阈值**：`> 0` (检测到超出滚动基线的额外错误时触发)
请注意，该查询会在日期范围开始前拉取 30 个时间间隔的数据，为滚动窗口计算提供初始值，然后再将最终输出过滤为仅包含评估窗口的数据。
## 常见告警场景
以下是一些可在 HyperDX 中使用的常见告警场景：
**错误：** 我们建议为默认的
`All Error Events` 和 `HTTP Status >= 400` 已保存搜索设置告警，以便在
错误数量过多时收到通知。
**慢操作：** 你可以为慢操作设置一个搜索 (例如
`duration:>5000`) ，然后在慢操作出现过多时
触发告警。
**用户事件：** 你还可以为面向客户的团队设置告警，以便在有新用户注册或发生关键用户操作时收到通知。