Prometheus 集成

TSE 前端搭载了一个 Prometheus 兼容适配器。无需单独的 Prometheus 服务器，即可直接使用 采集（remote_write）与可视化（PromQL） 的 Prometheus 生态。

[Prometheus · Grafana Agent] --remote_write--> TSE --> Cassandra
[Grafana (Prometheus 데이터소스)] --PromQL--> TSE

并非独立进程

适配器在 TSE 的 Jetty 内以 同一进程 运行。无需启动任何东西，也无需额外开放端口—— 只需将路径指向 /prometheus 即可（TSE 原生 API 位于 /api/v1/*）。认证也直接使用 TSE 的 Basic Auth。

1. 推送数据 — `remote_write`

在 prometheus.yml 或 Grafana Agent 配置中这样编写。

remote_write:
  - url: http://<TSE 호스트>:7800/prometheus/api/v1/write
    basic_auth:
      username: tse
      password: "<PP_TSE_PASSWORD>"

本文使用 snappy 压缩 + protobuf（remote_write 1.0），Prometheus 和 Agent 会自动处理。成功时返回 204，请求体错误时返回 400（不重试），临时故障时返回 500（会重试）。NaN 和 ±Inf 在 存储阶段会被丢弃。

2. 在 Grafana 中查看

将数据源类型选择为 Prometheus，并按如下填写。

项目	值
URL	`http://<TSE 호스트>:7800/prometheus`
Access	Server (proxy)
Auth	Basic auth — `tse` / `<PP_TSE_PASSWORD>`
HTTP Method	POST 推荐

点击「Save & Test」后，Grafana 会通过 /prometheus/api/v1/status/buildinfo 识别出这是 Prometheus。之后便可在面板中直接使用 PromQL。

与内置 PlantPulse Dashboard 的路径不同

TSE 还提供一个使用专用数据源插件的内置 PlantPulse Dashboard。两者任选其一即可——熟悉 PromQL 就选这边，如果要用预先构建的仪表盘则选内置的。

3. 映射关系

Prometheus	TSE
`__name__` 标签	指标名称
其他标签	标签
样本 `(ts_ms, float64)`	DataPoint（double，ms）

Prometheus 的命名规则（[a-zA-Z_:][a-zA-Z0-9_:]*）与 TSE 规则兼容，无损迁移。

4. 端点

均位于 /prometheus 之下，并遵循 Prometheus HTTP API 规范（{"status":"success","data":…}）。

方法·路径	用途
`POST /prometheus/api/v1/write`	remote_write 接收
`GET`·`POST` `/prometheus/api/v1/query`	即时查询
`GET`·`POST` `/prometheus/api/v1/query_range`	范围查询（`start`·`end`·`step`）
`GET /prometheus/api/v1/labels`	标签名称列表
`GET /prometheus/api/v1/label/{name}/values`	标签值列表
`GET`·`POST` `/prometheus/api/v1/series`	序列匹配（`match[]`）
`GET /prometheus/api/v1/status/buildinfo`	用于 Grafana 识别

时间使用 Unix 秒（可带小数）或 RFC3339，step 为 15s·1m·1h·500ms 或不带单位的秒。响应中的时间戳为秒，值为 字符串（Prometheus 规范）。

5. 可用的 PromQL

分类	支持内容
选择器	bare · 匹配器（`=` `!=` `=~` `!~`） · `__name__` 匹配器 · 范围选择器（`[5m]`，单位为 `ms s m h d w y`）
算术	数字字面量 · 一元 `-` · 括号 · `+ - * /` (scalar∘scalar, vector∘scalar, vector∘vector 1‑to‑1)
比较	`== != > < >= <=` （+ `bool`）
函数	`rate` `irate` `increase` `delta` · `abs` `clamp_min` `clamp_max` · `histogram_quantile`
聚合	`sum` `avg` `min` `max` `count` + `by`/`without` · `topk` `bottomk`

rate(errors[5m]) / rate(total[5m])
topk(5, sum(rate(req_total[5m])) by (path))
histogram_quantile(0.95, rate(latency_seconds_bucket[5m]))

6. 不支持的内容 — 不会静默出错，而是返回 400 拒绝

分类	不支持
向量匹配	`on(…)` · `ignoring(…)` · `group_left` · `group_right`
集合运算	`and` · `or` · `unless`
时间函数	`*_over_time` · `predict_linear` · `holt_winters`
变换	subquery（`expr[5m:1m]`） · `@` 修饰符 · `offset`
其他	`scalar()` `vector()` `label_replace()` `label_join()` `sort()` `sort_desc()` `absent()`
协议	`remote_read` · remote_write 2.0 · exemplars · native histogram

不支持的部分会以「错误」而非「错误的值」返回

不支持的语法会通过 400 {"status":"error","errorType":"bad_data",…} 中断。这意味着不会静默返回看似合理的数字，仪表盘不会 无提示地撒谎。

7. 细微差异

这并非完全的 Prometheus，而是 兼容适配器。实际使用中通常不成问题，但在需要精密比较数值时，需要了解这些差异。

项目	差异说明
`rate`·`increase` 外推	将观测区间线性外推到整个 range 范围（Prometheus 的边界外推上限未实现）——在区间边界处会有细微差异
range 窗口	`[t-range, t]` 包含两端（Prometheus 为左开区间）。即时选择器的 lookback 设为 `(t-5m, t]`，相同，默认 5 分钟
`/label/<name>/values`	`__name__` 是精确的，但其他标签采用全局标签值进行近似 — 对于自动补全已足够
scalar 比较	始终评估为 0 和 1（Prometheus 要求 `bool`）。`3 > 2` 直接返回 `1`

1. 推送数据 — remote_write​

2. 在 Grafana 中查看​

3. 映射关系​

4. 端点​

5. 可用的 PromQL​

6. 不支持的内容 — 不会静默出错，而是返回 400 拒绝​

7. 细微差异​

相关文档​