opensabre / opensabre/opensabre-framework

refactor: 将 Prometheus 查询能力迁移到监控控制面

Open
#73 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
403
Forks
121
Avg merge
52m
Merged PRs (30d)
2

Description

背景

当前 opensabre-starter-monitoring 同时包含两类职责:

  • 应用侧指标生产:Actuator/Micrometer 指标暴露、访问契约和安全默认值。
  • 控制面指标消费:PrometheusReadClient、Prometheus 服务地址以及固定 PromQL 查询模板。

PrometheusReadClient 查询 Prometheus 的直接用途是为 base-gateway-admin / opensabre-admin 提供 TPS、错误率、延迟和资源使用等监控展示数据。普通业务应用只负责暴露指标,不需要知道 Prometheus 地址,也不应主动查询 Prometheus。

问题

将 Prometheus 查询客户端放在 Framework 会让指标生产端与具体监控控制面耦合:

  • Framework 出现仅控制面使用的出站客户端和 Prometheus 地址配置。
  • 管理端需要增加 query_range、时间范围、步长、Top N 等展示查询时,会推动展示需求进入 Framework。
  • 固定 PromQL 模板包含网关/管理页面的具体聚合语义,不属于通用应用 Starter。

目标边界

  • opensabre-framework:负责 Micrometer/Actuator/Prometheus Registry、公共指标与标签契约、直方图默认值及指标端点安全。
  • base-gateway-admin:负责 Prometheus 即时与区间查询、固定 PromQL、结果转换、错误状态和面向 Admin 的监控 API。
  • opensabre-admin:负责时间范围选择和图形化展示。

建议改动

  1. base-gateway-admin 建立 Prometheus 查询适配层,覆盖 /api/v1/query/api/v1/query_range
  2. 将控制面专用的固定 PromQL 模板迁移到 base-gateway-admin
  3. opensabre.monitoring.prometheus.server-url 迁移为 base-gateway-admin 自有配置。
  4. 待所有调用方完成迁移后,从 opensabre-starter-monitoring 删除 PrometheusReadClient 和控制面专用查询模板。
  5. 保留 Framework 中应用侧指标暴露、安全和公共指标契约。
  6. 提供迁移说明;若存在外部调用方,先标记 deprecated,再在后续版本删除。

验收标准

  • 普通业务应用引入 monitoring starter 后不再包含或配置 Prometheus 查询客户端。
  • base-gateway-admin 可独立执行即时和区间查询。
  • 现有 /monitoring/routes/monitoring/applications 行为保持兼容。
  • 查询异常能区分未配置、不可达、查询失败和成功但无数据。
  • Framework 文档明确区分“指标生产端”和“监控控制面”。

与当前监控建设的关系

该重构是独立的架构债务,不作为 Prometheus 节点搭建和 Admin 图形化监控的前置条件。当前功能可以先在 base-gateway-admin 落地,后续按此 Issue 完成职责迁移和清理。

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating PrometheusReadClient, the opensabre.monitoring.prometheus.server-url property, the fixed PromQL templates, and the /monitoring/routes and /monitoring/applications entry points. Trace their current callers and any related tests or documentation across opensabre-starter-monitoring and base-gateway-admin. Done means query responsibilities are separated, existing monitoring behavior remains compatible, query failure states are distinguishable, and the migration guidance is documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, prometheus, spring-boot
Domain
api, backend, observability-sre
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.