docs: prometheus

Author: Ke-Wng

dir.yaml

@@ -345,6 +345,20 @@
       title_cn: Redis 兼容性
       path: key-value-data-model/redis-compatibility
 
+- title_en: Prometheus
+  title_cn: Prometheus 兼容
+  collapsed: true
+  children:
+    - title_en: Overview
+      title_cn: 概述
+      path: prometheus/overview
+    - title_en: Quick Start
+      title_cn: 快速开始
+      path: prometheus/quick-start
+    - title_en: PromQL Compatibility
+      title_cn: PromQL 兼容性
+      path: prometheus/promql-compatibility
+
 - title_en: Operation Guide
   title_cn: 运维指南
   collapsed: true

zh_CN/prometheus/overview.md

@@ -0,0 +1,11 @@
+# 概述
+Datalayers 支持 Prometheus 的 HTTP API 和 Remote Write 协议。通过这一特性，用户可以将现有的 Prometheus 生态工具无缝接入 Datalayers，无需修改代码即可实现数据写入和查询。
+
+# 主要特性
+- 兼容 Prometheus HTTP API，可直接对接 Grafana 等生态组件。
+- 兼容 Prometheus Remote Write 协议，可接收 Prometheus 的实时数据推送。
+- 支持 PromQL (Prometheus Query Language)，兼容主流查询语法与函数。
+
+# 核心价值
+- 平滑迁移： 无需修改现有的数据采集和可视化工具链。
+- 高性能/长期存储： 利用 Datalayers 的存储优势，解决原生 Prometheus 在大规模或长期存储场景下的性能和容量瓶颈。

zh_CN/prometheus/promql-compatibility.md

@@ -0,0 +1,19 @@
+# PromQL 兼容性
+
+## 选择器
+
+Datalayers 支持 Instant 选择器和 Range 选择器。并且对于普通标签，Datalayers 完整支持四种匹配运算符 (`=, !=, =~, !=`)。
+
+对于特殊标签 `__name__`, `__database__`，Datalayers 目前只支持等值匹配 (`=`)，其它运算符将返回错误。
+
+Datalayers 支持 `offset` 修饰符，但不支持 `@` 修饰符。
+
+## 运算符和函数
+
+| 类型 | 支持 | 不支持 |
+| :--- | :--- | :--- |
+| **运算符** | `neg`, `add`, `sub`, `mul`, `div`, `mod`, `eq`, `ne`, `gt`, `lt`, `ssgt`, `sslt`, `sseq`, `ssne`, `slt`, `sle`, `sge`, `power`, `atan2`, `and`, `or`, `unless` | 无 |
+| **聚合** | `sum`, `avg`, `min`, `max`, `stddev`, `stdvar`, `topk`, `bottomk`, `count_values`, `count`, `quantile`, `grouping`| `limitk`, `limit_ratio` |
+| **Instant 函数** | `abs`, `ceil`, `exp`, `ln`, `log2`, `log10`, `sqrt`, `acos`, `asin`, `atan`, `sin`, `cos`, `tan`, `acosh`, `asinh`, `atanh`, `sinh`, `cosh`, `scalar`, `tanh`, `timestamp`, `sort`, `sort_desc`, `histogram_quantile`, `predict_linear`, `absent`, `sgn`, `pi`, `deg`, `rad`, `floor`, `clamp`, `clamp_max`, `clamp_min` | 其它 `histogram_<aggr>` 函数|
+| **Range 函数** | `idelta`, `<aggr>_over_time` (如 `count_over_time`, `stddev_over_time`, `stdvar_over_time`), `changes`, `delta`, `rate`, `deriv`, `increase`, `irate`, `reset` | 无 |
+| **其他函数** | `label_join`, `label_replace`, `sort_by_label`, `sort_by_label_desc` | 无 |

zh_CN/prometheus/quick-start.md

@@ -0,0 +1,80 @@
+# Remote Write
+
+通过 Prometheus Remote Write 协议，可以将 Prometheus 中的数据快速导入 Datalayers。为此，您需要在 Prometheus 的配置文件中增加以下内容，将 Datalayers 设置为 Remote Write 端点：
+
+```
+remote_write:
+- url: https://<host>:<port>/api/v1/write
+  basic_auth:
+    username: <username>
+    password: <password>
+  headers:
+    database: <dbname>
+```
+
+其中：
+
+- `<host>` 和 `<port>` 分别表示 Datalayers 的 IP 地址和 HTTP 端口号
+- `<dbname>` 表示数据将要导入的数据库名称，该数据库需要预先创建
+- `<username>` 和 `<password>` 表示用于认证的用户名和密码
+
+# HTTP API
+
+导入 Datalayers 的数据可以通过以下 Prometheus HTTP API 进行查询：
+
+- Instant queries: `/api/v1/query`
+- Range queries: `/api/v1/query_range`
+- Series: `/api/v1/series`
+- Label names: `/api/v1/labels`
+- Label values: `/api/v1/label/<label_name>/values`
+
+这些接口的输入和输出与 Prometheus 保持一致，可以作为其直接替换。例如，您可以通过如下请求查询指标 `up` 在 `2025-07-22T10:00:00Z` 时刻的数据：
+
+```
+curl -v \
+  -u admin:public \
+  -H "database:prom" \
+  -d "query=up&time=2025-07-22T10:00:00Z" \
+  "http://localhost:9090/api/v1/query"
+```
+
+收到的响应形式如下：
+
+```
+{
+  "status": "success",
+  "data": {
+    "resultType": "vector",
+    "result": [
+      { "metric": { "__name__": "up", "sid": "s1", "flag": "ok" }, "value": [ 1753178400.0, "1" ] },
+      { "metric": { "__name__": "up", "sid": "s2", "flag": "fail" }, "value": [ 1753178400.0, "0" ] },
+      { "metric": { "__name__": "up", "sid": "s3", "flag": "ok" }, "value": [ 1753178400.0, "2" ] }
+    ]
+  }
+}
+```
+
+更多关于 HTTP API 的内容可参考![官方文档](https://prometheus.io/docs/prometheus/latest/querying/api/)。
+
+## 注意事项
+
+相较于 Prometheus，Datalayers 有额外的数据库的概念，每个 metric 都归属于某个数据库，因此在查询时需要显式指明数据库的名称。
+
+您可以通过两种方式指定数据库：
+
+1. 在 HTTP 请求的 header 中增加 `database: <dbname>`，之后查询的 metric 都会默认归属该数据库
+2. 或者通过标签 `__database__` 指定数据库，如 `up{__database__="dbname"}`。通过这种方式可以覆盖 HTTP header 中指定的数据库。
+
+# Grafana
+
+您可以直接将 Datalayers 作为 Prometheus 数据源添加到 Grafana 中，具体步骤如下：
+
+1. 在 Grafana 中 点击 Add new data source，选择 Prometheus 作为数据源
+
+2. 在 Remote server URL 中填入 Datalayers 的地址 `http://<host>:<port>`
+
+3. 在 Authentication method 中选择 Basic authentication，填入用户名和密码
+
+4. 在 Http headers 中增加 header `database: <dbname>`
+
+5. 点击 Save & Test 进行连通性测试，通过后进入面板编写 PromQL 进行查询