M0-07 Observability 基础版 #7

New Issue

wangdl · 2026-05-22T21:00:15+08:00

wangdl commented

2026-05-22 21:00:15 +08:00

目标

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

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

背景说明

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

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

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

模块职责

本模块负责：
- 请求级别 traceId 的生成和全链路透传
- 接口响应时间记录（interceptor 层面）
- AI 调用耗时记录
- 数据库慢查询检测和日志
- Worker 任务耗时记录
- 错误率统计（按接口/按模块）
- Admin 简单可视化（接口耗时排行、错误率趋势）
本模块不负责：
- 服务器 CPU/内存/磁盘监控（走 Server Monitor）
- 审计日志（走 Audit & Security）
- 用户行为分析
- 第三方 APM 集成（后续阶段）
- 告警推送（当前阶段不需要）

基础设施依赖判断

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

接口设计

Interceptor（无传统 API 路由）：
- MetricsInterceptor：拦截所有请求，记录耗时和状态码
- TraceIdInterceptor：生成和透传 traceId
Internal Provider：
- MetricsService.recordApiCall(data)：记录接口调用指标
- MetricsService.recordAICall(data)：记录 AI 调用指标
- MetricsService.recordTaskRun(data)：记录 Worker 任务指标
AAPI：
- 接口耗时排行
- 错误率统计
- AI 调用耗时统计
- 慢查询列表
- 按时间范围筛选

Admin 视图设计

概览页：
- 今日 API 调用量、平均耗时、错误率
- 今日 AI 调用量和平均耗时
- 错误率趋势图（简单折线或柱状图）
接口性能页：
- 接口耗时排行榜
- 单个接口的耗时变化趋势
- 慢接口标记
AI 调用页：
- AI 调用耗时统计（按 provider/模型分组）
- AI 调用失败率

交付检查

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

验收标准

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

禁止事项

禁止可观测性影响正常请求响应时间（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 调用失败率 ## 交付检查 - [x] 路由归属：Interceptor + Internal Provider + AAPI - [x] 是否需要 Prisma migration：是（指标存储表） - [x] 是否需要 MySQL：是 - [x] 是否需要 Redis：否 - [x] 是否需要 BullMQ：否 - [x] 是否需要 Qdrant：否 - [x] 是否需要 AI Gateway：否（采集方） - [x] 是否需要 Content Safety：否 - [x] 是否需要 Cost 记录：否 - [x] 是否需要 AuditLog：否 - [x] 是否需要 Domain Event：否（或可选） - [x] 是否需要 Admin 视图：是 - [x] 是否需要 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

wangdl commented

2026-05-22 23:19:43 +08:00

实施完成

新增文件

src/common/interceptors/metrics.interceptor.ts — 全量 API 耗时采集（fire-and-forget）
src/modules/admin-metrics/ — Admin 指标查询 AAPI

Admin API

端点	说明
GET /admin-api/metrics/overview	今日调用量、平均耗时、错误率、总量
GET /admin-api/metrics/top	接口耗时排行
GET /admin-api/metrics/recent	最近请求列表

数据表

ApiMetric: path/method/statusCode/duration/userId/ip

已有能力

TraceIdInterceptor — 全链路 trace-id 透传（M0-01 已完成）
MetricsInterceptor — 自动记录所有 API 耗时（本次新增）
Admin AAPI — 指标查询（本次新增）

待完成

Admin Web 可视化页面
慢查询检测
数据保留策略（TBD: 按天清理旧数据）

## 实施完成 ### 新增文件 - src/common/interceptors/metrics.interceptor.ts — 全量 API 耗时采集（fire-and-forget） - src/modules/admin-metrics/ — Admin 指标查询 AAPI ### Admin API | 端点 | 说明 | |------|------| | GET /admin-api/metrics/overview | 今日调用量、平均耗时、错误率、总量 | | GET /admin-api/metrics/top | 接口耗时排行 | | GET /admin-api/metrics/recent | 最近请求列表 | ### 数据表 - ApiMetric: path/method/statusCode/duration/userId/ip ### 已有能力 - TraceIdInterceptor — 全链路 trace-id 透传（M0-01 已完成） - MetricsInterceptor — 自动记录所有 API 耗时（本次新增） - Admin AAPI — 指标查询（本次新增） ### 待完成 - Admin Web 可视化页面 - 慢查询检测 - 数据保留策略（TBD: 按天清理旧数据）

wangdl commented

2026-05-24 09:38:22 +08:00

✅ E2E 测试通过

M0 E2E 测试已全部通过 — 28/28 tests passed，耗时 ~1.4s。

本 Issue 测试内容

API metrics interceptor records request, x-trace-id unique per request

运行方式

npm run test:e2e

测试架构

Mock 层: @prisma/client / ioredis / jose / @nestjs/bullmq
无需本地 MySQL/Redis，纯 mock 轻量集成测试
测试文件: test/m0.e2e-spec.ts

## ✅ E2E 测试通过 M0 E2E 测试已全部通过 — **28/28 tests passed**，耗时 ~1.4s。 ### 本 Issue 测试内容 API metrics interceptor records request, x-trace-id unique per request ### 运行方式 ```bash npm run test:e2e ``` ### 测试架构 - Mock 层: `@prisma/client` / `ioredis` / `jose` / `@nestjs/bullmq` - 无需本地 MySQL/Redis，纯 mock 轻量集成测试 - 测试文件: `test/m0.e2e-spec.ts`

~~wangdl referenced this issue 2026-06-05 19:34:41 +08:00~~

🟡 P1 | POST /knowledge-bases/{id}/folders 创建文件夹 #64

~~wangdl referenced this issue 2026-06-05 19:36:05 +08:00~~

🟡 P1 | POST /knowledge-bases/{id}/folders 创建文件夹 #64

wangdl closed this issue

2026-06-06 18:50:33 +08:00

wangdl commented

2026-06-06 18:50:34 +08:00