---
id: 006
title: 性能监控设计（epsilon 运行时 + xq CLI + GHA workflow 耗时）
status: open
labels: [observability, infra, sre]
assignee: team-lead
created_at: 2026-04-23
---

# #006 性能监控设计

## 场景

老板 2026-04-23 提出 —— 除了"防腐烂"（chaos engineering）外，还要持续看**性能**：
- epsilon 服务端 API 响应耗时 / 错误率
- sqlite 查询耗时（WHERE DSL 跑慢了）
- GHA workflow 耗时（release 链路耗时退化要早发现）
- xq CLI 本地响应时间

## 业界最佳实践

### Metrics stack

**大厂栈**（超配）：Prometheus + Grafana + Alertmanager + Loki 日志 + Tempo trace

**轻量栈**（适合两人团队）：
- **服务端 metrics**：FastAPI middleware 输出 access log（request method / path / latency / status code）到 journalctl
- **抓取方案**：
  - A) 用 **Uptime Kuma** 或 **Grafana Cloud free tier**（14 天数据）
  - B) 用 **statsd / Telegraf + InfluxDB Cloud** 免费档
  - C) 全 selfhost prometheus + grafana on epsilon（1C2G 够跑）
- **前端展示**：Grafana dashboard 或 GHA workflow 每天拉一次日志做 SLA 报告 + 徽章
- **告警**：latency p95 / 错误率超阈值发邮件 or IM

### 最小 viable（推荐先做）

**Step 1**：FastAPI middleware 记录每个请求的 path / method / latency_ms / status，append 到 `/opt/xiangqin/logs/access.jsonl`

**Step 2**：GHA workflow 每日拉 access.jsonl → Python 脚本算 p50 / p95 / p99 + 错误率 → 写到 `docs/assets/metrics/latest.json` → CF Pages 展示 + README 徽章

**Step 3**：如果 Step 2 数据太粗，再接 Grafana Cloud free tier（OTLP HTTP push）

**不要一开始做 Prometheus + Grafana selfhost**（两人团队运维负担大）。

## 覆盖维度

| 维度 | 怎么采 | 怎么看 |
|---|---|---|
| 服务端 API latency p95 | FastAPI middleware 写 jsonl | 每日 GHA 聚合 → 徽章 `api-p95: 45ms` |
| 服务端错误率 | 同上（status >=500 算错） | 徽章 `error-rate: 0.12%` |
| sqlite 慢查询 | `PRAGMA query_only`? 或代码包装 duration > 100ms log | 日志 grep |
| GHA workflow 耗时 | `gh api workflows/runs` 聚合 | 徽章 `release-latency: 3m` |
| xq CLI 响应 | 可选，CLI 加 `--profile` flag 本地测 | 不阻塞 |

## 不做

- **APM SaaS**（DataDog / New Relic）：付费贵、学习曲线陡
- **全链路 trace**（Tempo / Jaeger）：两人团队不需要

## 相关

- Chaos engineering #005（和性能监控是**防腐烂 vs 防降级**的双生议题）
- README 顶部徽章墙预留位置给性能徽章
