amit0101/sre-event-watchdog
GitHub: amit0101/sre-event-watchdog
一款 API 优先的智能可观测性工具，通过规则与 LLM 混合检测日志中的错误激增并触发告警，帮助 SRE 团队快速响应线上事件。
Stars: 0 | Forks: 0
# SRE Event Watchdog
API 优先的智能可观测性与事件监控工具 — 摄取 JSONL 日志，检测错误激增（规则 + LLM），触发 webhook 告警，并在 React dashboard 上展示健康趋势。
## 功能
- **日志摄取** — JSONL 上传、原始 body 和 JSON 批量 endpoint，支持可选的 API key
- **指标** — 窗口化错误聚合、按 service 分解、可过滤的时间序列
- **混合检测** — 按 service 的 EWMA 基线、趋势上下文、关联性、快速路径（60秒）、AI 分析
- **高弹性** — OpenAI 缓存、payload 截断、API 故障时自动降级
- **告警** — 去重、`open` → `ack` → `resolved` 生命周期、Slack Block Kit、webhook 重试
- **Dashboard** — **Ops 视图**（默认，监控风格）+ **经典视图**切换；图表过滤器；确认/解决操作；质量面板
## 架构
```
flowchart LR
generator[generate_logs.py] -->|JSONL| ingest[POST_logs_ingest]
ingest --> ingestion[IngestionService]
ingestion --> db[(log_events)]
db --> metrics[MetricsService]
metrics --> detection[RuleDetection]
detection -->|spike| ai[AIAnalyzer]
detection -->|acute| fast[FastPath]
ai --> alerts[(alerts)]
fast --> alerts
alerts --> webhook[WebhookDispatcher]
webhook --> mock[mock_webhook]
db --> dashboard[ReactDashboard]
alerts --> dashboard
```
## 环境要求
- Python 3.13
- Node.js 18+（用于构建 dashboard）
- OpenAI API key
## 快速开始
```
# 后端设置
python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# 在 .env 中设置 OPENAI_API_KEY
# 运行 API（当 frontend/dist 存在时提供已构建的 dashboard）
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
```
### 构建 dashboard（单服务器演示）
```
cd frontend
npm install
npm run build
cd ..
uvicorn app.main:app --host 127.0.0.1 --port 8000
# Dashboard: http://127.0.0.1:8000/（默认为 Ops 视图；在右上角切换至 Classic）
```
### 前端开发模式（热重载 + API 代理）
```
# 终端 1
uvicorn app.main:app --reload --port 8000
# 终端 2
cd frontend && npm install && npm run dev
# Dashboard 开发: http://127.0.0.1:5173
```
## 演示导览
```
# 1. 生成带有错误激增的日志
python generate_logs.py --spike -n 150 -o spike.jsonl
# 关联级联（auth → payment）
python generate_logs.py --correlated-spike -n 150 -o correlated.jsonl
# spike 窗口期间的高延迟错误
python generate_logs.py --spike --latency-spike -n 150 -o latency.jsonl
# 2. 摄取
curl -F "file=@spike.jsonl" http://127.0.0.1:8000/logs/ingest
# 3. 查看 metrics
curl "http://127.0.0.1:8000/metrics/errors?window_minutes=60"
curl "http://127.0.0.1:8000/metrics/timeseries?window_minutes=60&level=ERROR"
curl "http://127.0.0.1:8000/metrics/levels?window_minutes=60"
# 4. 运行检测 + AI enrichment + webhook
curl -X POST http://127.0.0.1:8000/analyze -H "Content-Type: application/json" -d '{"window_minutes":5}'
# 5. Alert 生命周期
curl http://127.0.0.1:8000/alerts
curl -X PATCH http://127.0.0.1:8000/alerts/1/ack -H "Content-Type: application/json" -d '{"ack_by":"oncall"}'
curl -X PATCH http://127.0.0.1:8000/alerts/1/resolution -H "Content-Type: application/json" -d '{"resolution":"true_positive"}'
# 6. 质量报告
curl "http://127.0.0.1:8000/alerts/quality-report?days=7"
# 7. 检查 mock webhook 回执
curl http://127.0.0.1:8000/mock-webhook/received
```
或者在摄取日志后使用 dashboard 上的 **分析** 按钮。
## API Endpoints
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| POST | `/logs/ingest` | 上传 JSONL 日志文件 |
| POST | `/logs/ingest/raw` | 摄取原始 JSONL body |
| POST | `/logs/ingest/batch` | 摄取包含多个事件的 JSON 数组 |
| GET | `/metrics/errors` | 按时间桶分组的错误计数/比率 |
| GET | `/metrics/timeseries` | 可过滤的图表序列（level, service） |
| GET | `/metrics/levels` | 按 level 计数，用于过滤器标签 |
| GET | `/metrics/health` | 后端健康评分 |
| GET | `/metrics/services` | 按 service 划分的错误分解 |
| POST | `/analyze` | 运行激增检测、AI 分析、告警 + webhook |
| GET | `/alerts` | 列出最近的告警 |
| PATCH | `/alerts/{id}/ack` | 确认告警（`open` → `ack`） |
| PATCH | `/alerts/{id}/resolution` | 解决告警（`true_positive`、`false_positive` 等） |
| GET | `/alerts/quality-report` | 告警质量指标 |
| GET | `/health` | 存活探针 |
| GET | `/ready` | 就绪状态（DB 可达） |
| POST | `/mock-webhook` | 本地 webhook 接收端 |
| GET | `/docs` | OpenAPI/Swagger UI |
## 日志格式（JSONL）
```
{"timestamp":"2026-07-12T10:00:00Z","level":"ERROR","service":"payment-service","message":"timeout","trace_id":"abc-123","host":"host-a","pod":"pod-1","region":"us-east-1","http_status":503,"latency_ms":2400}
```
字段：`timestamp` (ISO8601)、`level` (`INFO|WARN|ERROR`)、`service`、`message`，以及可选的 `trace_id`、`host`、`pod`、`region`、`http_status`、`latency_ms`。
## 环境变量
| 变量 | 必填 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `OPENAI_API_KEY` | 是 | — | OpenAI API key |
| `OPENAI_MODEL` | 否 | `gpt-4o-mini` | 用于 AI 分析的模型 |
| `DATABASE_URL` | 否 | `sqlite:///./watchdog.db` | SQLAlchemy DB URL |
| `WEBHOOK_URL` | 否 | `http://127.0.0.1:8000/mock-webhook` | 告警 webhook 目标地址 |
| `WEBHOOK_MAX_RETRIES` | 否 | `3` | webhook 投递重试次数 |
| `FAST_PATH_INTERVAL_SECONDS` | 否 | `18` | 快速路径调度器频率 |
| `INGEST_API_KEY` | 否 | — | 可选的摄取认证 header |
## 生产环境数据库
本地开发使用 SQLite。在生产环境中，请将 `DATABASE_URL` 设置为 Postgres（例如 Supabase）：
```
DATABASE_URL=postgresql+psycopg://user:pass@host:5432/watchdog
```
安装驱动：`pip install psycopg[binary]`。无需修改任何应用代码。
## 测试
```
pytest -v
```
## 项目结构
```
app/
main.py # FastAPI app factory
config.py # pydantic-settings
db.py, models.py # SQLAlchemy layer
schemas.py # Pydantic DTOs
api/ # REST routers
services/ # ingestion, metrics, detection, ai, alerting, correlation, fast_path
frontend/ # React SPA (Vite + Recharts) — Ops + Classic views
tests/ # pytest suite (62 cases)
generate_logs.py # synthetic log generator (--spike, --correlated-spike, --latency-spike)
sample_logs.jsonl # sample data
DEVELOPMENT_PLAN.md # build progress tracker
DETECTION_ENHANCEMENTS.md # statistical detection phases 0–9
DECK_OUTLINE.md # presentation outline
PRESENTATION.md # submission deck (Markdown source)
docs/presentation/ # print-ready PDF + rendered diagram assets
prompts.md # prompt audit log
```
## 演示文稿
- **Markdown:** [`PRESENTATION.md`](PRESENTATION.md)
- **PDF (打印就绪):** [`docs/presentation/SRE_Event_Watchdog_Presentation.pdf`](docs/presentation/SRE_Event_Watchdog_Presentation.pdf)
使用 `python scripts/build_presentation.py` 重新生成（选项详见 [`SUBMISSION.md`](SUBMISSION.md)）。
## 生产环境就绪度
当前的 MVP 提供了一个可运行的端到端监控工具。生产环境将填补以下空白（完整详情见演示文稿第 15 页）：
| 领域 | MVP (当前版本) | 生产环境路径 |
|------|---------------|-----------------|
| 数据库 | SQLite，可通过 `DATABASE_URL` 替换 | Postgres + 连接池 |
| 迁移 | Alembic 版本控制 | 读副本、按时间分区的事件 |
| 摄取 | 批量 POST | 队列/流处理 (Kafka/Redis) + workers |
| 检测 | 基于聚合数据的规则 + LLM | 流式聚合或时间序列数据库 |
| 认证 | 可选的 `INGEST_API_KEY` | OAuth2/OIDC，密钥管理器 |
| 告警 | 去重、生命周期、webhook 重试 | 冷静期、严重性路由、多渠道 |
| 可观测性 | `/health`、`/ready` | 结构化 JSON 日志、请求 ID、Prometheus、链路追踪 |
| CI/CD | 本地 pytest | GitHub Actions、Dockerfile、docker-compose |
| 数据保留 | 保留所有事件 | 汇总数据、TTL、归档层级 |
**已覆盖：** pydantic-settings、DB 索引、LLM 超时/重试/降级、分析缓存、告警去重 + `open`→`ack`→`resolved`、Slack Block Kit、62 个 pytest 测试用例。
## 许可证
MIT (演示 / 教学项目)
标签：API集成, MITM代理, React, SRE, Syscalls, 偏差过滤, 可观测性, 安全规则引擎, 异常检测, 测试用例, 监控告警, 逆向工具