refactor docs

Author: UlricQin

content/zh/docs/usage/ad-hoc.md

@@ -1,7 +1,8 @@
 ---
 title: "Ad-hoc 查询"
+description: "夜莺监控（Nightingale）支持 Ad-hoc 查询，可以在界面上直接查询数据源的数据。既可以查询时序指标数据，也可以查询日志数据。"
 date: 2025-01-26T11:23:54+08:00
-lastmod: 2025-01-26T11:23:54+08:00
+lastmod: 2025-05-31T22:48:53.293+08:00
 draft: false
 images: []
 menu:
@@ -11,6 +12,28 @@ weight: 1100
 toc: true
 ---
 
-夜莺支持 Ad-hoc 查询，可以在界面上直接查询数据源的数据。在 `时序指标-即时查询` 菜单查询指标数据，在 `日志分析-即时查询` 菜单查询日志数据。
+夜莺支持 Ad-hoc 查询，可以在界面上直接查询数据源的数据。菜单入口在 `数据查询` 下面，选择 `指标` 可以查询指标数据，选择 `日志` 可以查询日志数据。
+
+## 指标查询
+
+下面是一个指标查询样例：
 
 <img src="/img/usage/ad-hoc/metric-explorer_zh.png" alt="指标查询"/>
+
+这个页面和 Prometheus 的 `graph` 页面类似，支持查询时序指标数据。当然也做了一些增强，增加了内置指标、历史记录等等一些能力。上图中是一个 range vector，且使用的 Table 视图，此时夜莺会多做一步，计算各个数据的时间差，就是最右侧那个 `+15`，方便我们排查是否有数据丢失的情况，比如大都是规律的时间差，和采集频率一致，但是突然发现有两个时间差比较大，是好几倍的采集频率，那就表示有数据采集或传输失败了。
+
+> 经常被新手询问的问题是，这个页面一进来为啥看不到任何数据。这是符合预期的，需要先输入 Promql 进行查询，然后才能看到数据。而非是说一进来这个页面就可以看到数据。Promql 是使用 Prometheus、Nightingale 的前置知识，建议先学习 Promql 的基础知识，资料参考：《[Promql系列教程](https://flashcat.cloud/tags/promql/)》
+
+如果使用的采集器是 Categraf，可以查询 `cpu_usage_active` 这个指标，如果能查到，说明数据源配置是 OK 的。如果使用的采集器是 Node-Exporter，那可以查询 `node_load1` 这个指标，如果能查到，说明数据源配置是 OK 的。
+
+## 日志查询
+
+日志查询主要是支持的 ElasticSearch 数据源，配置 ElasticSearch 数据源的时候，有个版本字段很多人会有困惑，如果你是 `6.x` 版本的 ElasticSearch，那么就选择 `6.0+` 版本，如果是 `7.x` 版本的 ElasticSearch，就选择 `7.0+` 版本，如果是更高版本，也直接选择 `7.0+` 版本，如果遇到不兼容的情况，提 issues 反馈即可。
+
+配置完了数据源之后，可以在 `数据查询-日志` 页面进行查询，下面是一个日志查询样例：
+
+<img src="/img/usage/ad-hoc/log-explorer_zh.png" alt="日志查询"/>
+
+和 Kibana 的日志查询页面很像，夜莺这里既可以支持按照索引模式查询，也可以不创建索引模式，直接查询索引（支持通配符），不过直接查询索引不是一个好的实践，后面可能会下掉这个功能。另外查询语法支持 KQL 和 Lucene（即 query string）两种，对于 ElasticSearch 的玩家而言，这些概念都不陌生，这里就不赘述了。
+
+数据源配置成功之后，下一步就可以进入重头戏了，配置告警规则，体验夜莺的告警引擎能力。

content/zh/docs/usage/alert-rules.md

@@ -12,12 +12,26 @@ weight: 1000
 toc: true
 ---
 
-夜莺支持对接各类数据源，前期支持的数据源，比如 Prometheus、VictoriaMetrics、ElasticSearch 等，既支持查询看图，也支持告警。后面随着项目发展，夜莺定位为一个告警引擎，数据源的查询看图功能会逐渐弱化，主要还是用于告警。所以新对接的数据源，比如 ClickHouse、MySQL、Postgres 等，都是只支持告警，不支持查询看图。
+夜莺支持对接各类数据源，前期支持的数据源，比如 Prometheus、VictoriaMetrics、ElasticSearch 等，既支持查询看图，也支持告警。后面随着项目发展，夜莺定位为一个告警引擎，所以新对接的数据源，比如 ClickHouse、MySQL、Postgres 等，都是只支持告警，不支持查询看图。
 
-在 `集成中心-数据源` 中添加数据源，选择对应的数据源类型，填写数据源的地址、用户名、密码等信息，点击保存即可。
+不管是要查看数据源里的数据，还是对数据源里的数据进行告警，都需要先配置数据源。在 `集成中心-数据源` 中添加数据源，选择对应的数据源类型，填写数据源的地址、用户名、密码等信息，点击保存即可。
 
 <img src="/img/usage/datasource/list_zh.png" alt="数据源"/>
 
 配置数据源时，除了要填写数据源的连接地址，另一个关键点是要选择关联的告警引擎，如果你的数据源是在边缘机房的，并且为边缘机房搭建了专属的 n9e-edge，那么就选择对应的 n9e-edge 作为关联的告警引擎。
 
 数据源配置中，表单各项基本都对应有 tooltip（就是各个 form 表单旁边的小问号 icon，鼠标放上去可以看到用法提示），这里就不再赘述了。
+
+配置完了数据源之后，可以到[即时查询页面](/zh/docs/usage/ad-hoc/)查询一下时序库的数据，如果能查到数据，则表明数据源的配置是 OK 的。
+
+## 常见问题
+
+**1. 夜莺的配置文件 config.toml 中已经配置了数据源的 writer 地址，是否还需要在页面上重复配置？**
+
+是的。config.toml 中的 writer 地址，是用于数据转发链路，而页面上的数据源配置，是用于查询和告警的。两者是不同的概念。另外，writer 地址应该是一个 remote write 地址，而页面上的数据源配置通常是数据源的基准地址。另外，很多用户也没有使用夜莺转发监控指标，所以也就没有配置 config.toml 中的 writer 地址，仅配置了页面上的数据源。
+
+**2. 我想采用边缘模式对边缘机房的时序库做告警，但是中心端的 n9e 无法连通边缘的时序库，这种情况还能用夜莺做统一告警吗？**
+
+可以。这类边缘时序库，仍然需要在页面上添加，添加的时候选择「保存」而非选择「测试并保存」，这样一来，中心端的夜莺就不会校验连通性，可以直接保存成功。同时，数据源配置的时候，要配置上时序库内网地址，告警引擎选择和时序库能连通的 n9e-edge 告警引擎，届时 n9e-edge 会使用时序库内网地址进行查询和告警。
+
+这种情况的边缘时序库，仍然可以告警，但是在夜莺的页面上就没法查询其数据了。因为夜莺的页面查询数据是通过中心端的 n9e 进行的，而中心端的 n9e 无法连通边缘时序库，所以无法查询。

content/zh/docs/usage/datasource.md

@@ -0,0 +1,26 @@
+---
+title: "指标告警"
+description: "夜莺监控（Nightingale）支持指标告警，根据用户配置的告警规则，周期性查询数据源，当数据源中的数据满足告警阈值时，触发告警。"
+date: 2025-01-26T11:45:54+08:00
+lastmod: 2025-05-31T23:10:28.891+08:00
+draft: false
+images: []
+menu:
+  docs:
+    parent: "usage"
+weight: 1200
+toc: true
+---
+
+夜莺监控（Nightingale）把告警分成告警+通知两个部分，告警指的是通过规则，周期性判定，最终产生告警事件，通知指的是告警事件的后续 Pipeline 和通知流程。本章节先介绍告警部分，最终能产生告警事件咱就算成功。
+
+## 告警原理
+
+夜莺支持两个告警模式，普通模式和高级模式：
+
+- 普通模式：在 Promql 中配置告警阈值，`查询条件` 和 `阈值设置` 在一起，没有特殊需求的话就使用普通模式即可，这个模式就和 Prometheus 的告警逻辑是一样的，性能比较好。不过告警恢复时要想拿到恢复时的值稍微麻烦点
+- 高级模式：`查询条件` 和 `阈值设置` 分开，如果有多个查询条件需要做加减乘除计算，可以使用高级模式，在告警事件的现场值中会将每个查询条件的值展示出来，在告警恢复时也可以轻松拿到恢复时的值
+
+### 普通模式的原理
+
+未完待续...