wangdl/api-server
2
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

M0-07 Observability 基础版 #7

New Issue
Open
opened 2026-05-22 21:00:15 +08:00 by wangdl · 0 comments
wangdl commented 2026-05-22 21:00:15 +08:00
Owner
Copy Link

目标

设计知习后端应用可观测性模块，为全系统提供统一的 traceId 透传、接口耗时追踪、慢查询日志和基础可视化能力。

本 Issue 只做架构设计，不直接实现代码。

背景说明

当系统上线后出现"某个接口突然变慢"或"AI 调用超时频发"时，如果没有任何可观测性基础设施，排查问题等于大海捞针。Observability 模块解决的就是"系统到底哪里出了问题"。

注意区分：Observability 看应用层面的性能（接口耗时、AI 调用耗时、数据库查询耗时），Server Monitor 看服务器和容器是否存活（CPU/内存/磁盘/Docker 状态）。

本阶段只做基础版：traceId 全链路透传 + 接口耗时 interceptor + 慢查询日志 + Admin 简单可视化。不上 Tempo/Loki/Grafana 等重型组件。

模块职责

  1. 本模块负责：

    • 请求级别 traceId 的生成和全链路透传
    • 接口响应时间记录（interceptor 层面）
    • AI 调用耗时记录
    • 数据库慢查询检测和日志
    • Worker 任务耗时记录
    • 错误率统计（按接口/按模块）
    • Admin 简单可视化（接口耗时排行、错误率趋势）

  2. 本模块不负责：

    • 服务器 CPU/内存/磁盘监控（走 Server Monitor）
    • 审计日志（走 Audit & Security）
    • 用户行为分析
    • 第三方 APM 集成（后续阶段）
    • 告警推送（当前阶段不需要）

基础设施依赖判断

  • MySQL：是（性能指标持久化，用于历史趋势查询）
  • Redis：否（指标收集不需要缓存）
  • BullMQ：否（指标记录可异步，但建议轻量同步避免延迟）
  • Qdrant：否
  • AI Gateway：否（但需要采集 AI Gateway 的调用耗时数据）
  • COS：否
  • Config：是（可观测性开关和采样率配置）

接口设计

  1. Interceptor（无传统 API 路由）：

    • MetricsInterceptor：拦截所有请求，记录耗时和状态码
    • TraceIdInterceptor：生成和透传 traceId

  2. Internal Provider：

    • MetricsService.recordApiCall(data)：记录接口调用指标
    • MetricsService.recordAICall(data)：记录 AI 调用指标
    • MetricsService.recordTaskRun(data)：记录 Worker 任务指标

  3. AAPI：

    • 接口耗时排行
    • 错误率统计
    • AI 调用耗时统计
    • 慢查询列表
    • 按时间范围筛选

Admin 视图设计

  1. 概览页：

    • 今日 API 调用量、平均耗时、错误率
    • 今日 AI 调用量和平均耗时
    • 错误率趋势图（简单折线或柱状图）

  2. 接口性能页：

    • 接口耗时排行榜
    • 单个接口的耗时变化趋势
    • 慢接口标记

  3. AI 调用页：

    • AI 调用耗时统计（按 provider/模型分组）
    • AI 调用失败率

交付检查

  • 路由归属：Interceptor + Internal Provider + AAPI
  • 是否需要 Prisma migration：是（指标存储表）
  • 是否需要 MySQL：是
  • 是否需要 Redis：否
  • 是否需要 BullMQ：否
  • 是否需要 Qdrant：否
  • 是否需要 AI Gateway：否（采集方）
  • 是否需要 Content Safety：否
  • 是否需要 Cost 记录：否
  • 是否需要 AuditLog：否
  • 是否需要 Domain Event：否（或可选）
  • 是否需要 Admin 视图：是
  • 是否需要 E2E/集成测试：是

验收标准

  1. TraceId 生成和全链路透传方案
  2. MetricsInterceptor 接口耗时记录方案
  3. 慢查询检测机制（数据库层面或 ORM 层面）
  4. AI 调用耗时采集方案
  5. Admin 可视化视图设计
  6. 指标数据保留策略（多久清理一次旧数据）
  7. 集成测试覆盖指标记录和查询

禁止事项

  • 禁止可观测性影响正常请求响应时间（interceptor 应轻量）
  • 禁止在 MetricsInterceptor 中做复杂计算
  • 禁止指标数据无限增长（必须有保留策略）
  • 禁止在请求中暴露内部 traceId 给 C 端用户
  • 禁止每个模块自己实现计时逻辑（必须统一走 MetricsService）

不建议当前阶段实现

  • OpenTelemetry 完整集成
  • Grafana Tempo/Loki 对接
  • 分布式链路追踪可视化
  • 自动告警规则
  • 指标聚合和降采样
## 目标 设计知习后端应用可观测性模块，为全系统提供统一的 traceId 透传、接口耗时追踪、慢查询日志和基础可视化能力。 本 Issue 只做架构设计，不直接实现代码。 ## 背景说明 当系统上线后出现"某个接口突然变慢"或"AI 调用超时频发"时，如果没有任何可观测性基础设施，排查问题等于大海捞针。Observability 模块解决的就是"系统到底哪里出了问题"。 注意区分：Observability 看应用层面的性能（接口耗时、AI 调用耗时、数据库查询耗时），Server Monitor 看服务器和容器是否存活（CPU/内存/磁盘/Docker 状态）。 本阶段只做基础版：traceId 全链路透传 + 接口耗时 interceptor + 慢查询日志 + Admin 简单可视化。不上 Tempo/Loki/Grafana 等重型组件。 ## 模块职责 1. 本模块负责： - 请求级别 traceId 的生成和全链路透传 - 接口响应时间记录（interceptor 层面） - AI 调用耗时记录 - 数据库慢查询检测和日志 - Worker 任务耗时记录 - 错误率统计（按接口/按模块） - Admin 简单可视化（接口耗时排行、错误率趋势） 2. 本模块不负责： - 服务器 CPU/内存/磁盘监控（走 Server Monitor） - 审计日志（走 Audit & Security） - 用户行为分析 - 第三方 APM 集成（后续阶段） - 告警推送（当前阶段不需要） ## 基础设施依赖判断 - MySQL：是（性能指标持久化，用于历史趋势查询） - Redis：否（指标收集不需要缓存） - BullMQ：否（指标记录可异步，但建议轻量同步避免延迟） - Qdrant：否 - AI Gateway：否（但需要采集 AI Gateway 的调用耗时数据） - COS：否 - Config：是（可观测性开关和采样率配置） ## 接口设计 1. Interceptor（无传统 API 路由）： - MetricsInterceptor：拦截所有请求，记录耗时和状态码 - TraceIdInterceptor：生成和透传 traceId 2. Internal Provider： - MetricsService.recordApiCall(data)：记录接口调用指标 - MetricsService.recordAICall(data)：记录 AI 调用指标 - MetricsService.recordTaskRun(data)：记录 Worker 任务指标 3. AAPI： - 接口耗时排行 - 错误率统计 - AI 调用耗时统计 - 慢查询列表 - 按时间范围筛选 ## Admin 视图设计 1. 概览页： - 今日 API 调用量、平均耗时、错误率 - 今日 AI 调用量和平均耗时 - 错误率趋势图（简单折线或柱状图） 2. 接口性能页： - 接口耗时排行榜 - 单个接口的耗时变化趋势 - 慢接口标记 3. AI 调用页： - AI 调用耗时统计（按 provider/模型分组） - AI 调用失败率 ## 交付检查 - [ ] 路由归属：Interceptor + Internal Provider + AAPI - [ ] 是否需要 Prisma migration：是（指标存储表） - [ ] 是否需要 MySQL：是 - [ ] 是否需要 Redis：否 - [ ] 是否需要 BullMQ：否 - [ ] 是否需要 Qdrant：否 - [ ] 是否需要 AI Gateway：否（采集方） - [ ] 是否需要 Content Safety：否 - [ ] 是否需要 Cost 记录：否 - [ ] 是否需要 AuditLog：否 - [ ] 是否需要 Domain Event：否（或可选） - [ ] 是否需要 Admin 视图：是 - [ ] 是否需要 E2E/集成测试：是 ## 验收标准 1. TraceId 生成和全链路透传方案 2. MetricsInterceptor 接口耗时记录方案 3. 慢查询检测机制（数据库层面或 ORM 层面） 4. AI 调用耗时采集方案 5. Admin 可视化视图设计 6. 指标数据保留策略（多久清理一次旧数据） 7. 集成测试覆盖指标记录和查询 ## 禁止事项 - 禁止可观测性影响正常请求响应时间（interceptor 应轻量） - 禁止在 MetricsInterceptor 中做复杂计算 - 禁止指标数据无限增长（必须有保留策略） - 禁止在请求中暴露内部 traceId 给 C 端用户 - 禁止每个模块自己实现计时逻辑（必须统一走 MetricsService） ## 不建议当前阶段实现 - OpenTelemetry 完整集成 - Grafana Tempo/Loki 对接 - 分布式链路追踪可视化 - 自动告警规则 - 指标聚合和降采样
wangdl added this to the M0：后端基础能力与架构规范闭环（P0） milestone 2026-05-22 21:00:15 +08:00
wangdl self-assigned this 2026-05-22 21:00:15 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone M0：后端基础能力与架构规范闭环（P0）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees wangdl
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#7
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?