feat(observability): Prometheus /metrics 端点——接入 Grafana 生态
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 4
- Forks
- 0
- Avg merge
- 3h 28m
- Merged PRs (30d)
- 9
Description
背景
请求量、错误率、耗时、熔断状态、队列深度等运行数据目前只活在自建面板(dashboard / live pulse / rankings)里,无法接入外部监控生态。生产环境已是 docker-compose 部署,加一个 Prometheus 抓取端点即可挂进 Grafana / Alertmanager 等标准工具链。
方案:/metrics 端点
暴露 Prometheus 文本格式的指标端点,首批指标:
| 指标 | 类型 | 标签 |
|---|---|---|
| 请求总数 / 错误数 | counter | upstream, capability, status_class |
| 请求耗时 / 首字节耗时 | histogram | upstream, capability |
| token 用量(输入/输出) | counter | upstream, model |
| 熔断器状态 | gauge | upstream |
| 上游健康状态 | gauge | upstream |
| 并发占用 / 队列深度 | gauge | upstream |
| 累计花费 | counter | upstream |
设计要点
- 指标在进程内存中累计(prom-client 或等价轻量实现),不查库,抓取零成本;进程重启计数归零符合 Prometheus counter 语义。
- 埋点挂在现有链路节点:
request-logger记录处、熔断状态迁移处、队列准入处,避免新增旁路统计。 - 端点鉴权:Bearer token(可复用 ADMIN_TOKEN 或独立的 METRICS_TOKEN 环境变量),未配置时端点关闭。
- 标签基数控制:model 标签需白名单或截断口径,防止任意请求模型名撑爆基数。
- 上游标签用 ID+名称,注意与“下游响应不携带上游身份”的约束区分——metrics 是管理侧出口,不受该约束,但需鉴权保护。
后续可扩展(本期不做)
- OpenAI 兼容的 usage/dashboard API,供第三方用量统计工具直读。
- Grafana dashboard JSON 模板随文档发布。
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing the existing request-logger path, circuit-breaker state transitions, and queue-admission logic mentioned in the issue. Check how the TypeScript service exposes authenticated endpoints and how docker-compose configures deployment. Done means an optionally enabled, authenticated /metrics endpoint exposes the listed Prometheus metrics with controlled label cardinality and no database queries.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker-compose, grafana, prometheus, typescript
- Domain
- backend, devops, observability
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100