534 lines
14 KiB
Markdown
534 lines
14 KiB
Markdown
# 数据聚合与存储设计文档
|
||
|
||
## 一、设计原则
|
||
|
||
### 1.1 存储分层策略
|
||
|
||
```
|
||
热数据（7天内） ←→ Loki + MySQL（高频查询）
|
||
温数据（7-30天） ←→ Loki（低频查询）
|
||
冷数据（30天+） ←→ 对象存储归档（极少查询）
|
||
```
|
||
|
||
### 1.2 存储选型
|
||
|
||
| 数据类型 | 存储 | 保留时长 | 说明 |
|
||
|----------|------|----------|------|
|
||
| 原始错误事件 | Loki | 7-30 天 | 堆栈、上下文、面包屑 |
|
||
| 原始性能事件 | Loki | 7 天 | 性能明细数据 |
|
||
| 原始行为事件 | Loki | 3 天 | PV、点击等（量大） |
|
||
| 错误聚合统计 | MySQL | 永久 | 按指纹 + 时间聚合 |
|
||
| 性能指标统计 | MySQL | 90 天 | 按指标 + 时间聚合 |
|
||
| 项目配置 | MySQL | 永久 | 项目、用户、告警规则 |
|
||
| 告警记录 | MySQL | 90 天 | 告警历史 |
|
||
|
||
### 1.3 设计目标
|
||
|
||
- **Loki 存储成本**：100万错误事件 ≈ 5GB/月
|
||
- **MySQL 存储成本**：聚合数据 ≈ 100MB/月/项目
|
||
- **查询性能**：聚合查询 < 100ms，原始日志查询 < 2s
|
||
|
||
---
|
||
|
||
## 二、Loki 存储设计
|
||
|
||
### 2.1 Label 设计
|
||
|
||
Loki 的 Label 是查询索引，设计原则：**低基数、高区分度**。
|
||
|
||
| Label | 说明 | 基数 | 示例 |
|
||
|-------|------|------|------|
|
||
| `project_id` | 项目 ID | 低（项目数） | 1001 |
|
||
| `type` | 事件类型 | 极低 | error / performance / network / behavior |
|
||
| `level` | 日志级别 | 极低 | fatal / error / warning / info |
|
||
| `platform` | 平台 | 低 | javascript / node / python |
|
||
| `environment` | 环境 | 低 | production / staging / development |
|
||
| `fingerprint` | 错误指纹 | 中 | abc123def |
|
||
|
||
**反模式（不要用做 Label）**：
|
||
- ❌ `event_id`：基数太高，每个事件都不同
|
||
- ❌ `message`：基数太高，且是文本
|
||
- ❌ `url`：基数太高
|
||
- ❌ `user_id`：基数太高
|
||
|
||
这些应该放在日志内容里，用 grep 查询。
|
||
|
||
### 2.2 日志格式（JSON）
|
||
|
||
每条日志是一行 JSON，方便 Loki 的 `json` 解析器提取字段。
|
||
|
||
#### 错误事件格式
|
||
|
||
```json
|
||
{
|
||
"event_id": "abc123...",
|
||
"type": "error",
|
||
"level": "error",
|
||
"timestamp": 1704067200000,
|
||
"project_id": "1001",
|
||
"platform": "javascript",
|
||
"environment": "production",
|
||
"release": "1.0.0",
|
||
"fingerprint": "a1b2c3d4e5f6",
|
||
|
||
"message": "Cannot read property 'foo' of undefined",
|
||
"exception": {
|
||
"type": "TypeError",
|
||
"value": "Cannot read property 'foo' of undefined",
|
||
"stacktrace": {
|
||
"frames": [
|
||
{
|
||
"filename": "https://example.com/app.js",
|
||
"function": "onClick",
|
||
"lineno": 123,
|
||
"colno": 45,
|
||
"in_app": true
|
||
}
|
||
]
|
||
}
|
||
},
|
||
|
||
"user": {
|
||
"id": "123",
|
||
"username": "testuser"
|
||
},
|
||
|
||
"tags": {
|
||
"page": "/home",
|
||
"browser": "Chrome 120"
|
||
},
|
||
|
||
"extra": {},
|
||
"breadcrumbs": [],
|
||
|
||
"request": {
|
||
"url": "https://example.com/page",
|
||
"headers": {
|
||
"user_agent": "Mozilla/5.0..."
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 性能事件格式
|
||
|
||
```json
|
||
{
|
||
"type": "performance",
|
||
"level": "info",
|
||
"timestamp": 1704067200000,
|
||
"project_id": "1001",
|
||
|
||
"metric": "lcp",
|
||
"value": 2500,
|
||
"unit": "ms",
|
||
"rating": "good",
|
||
|
||
"tags": {
|
||
"page_url": "https://example.com/page",
|
||
"route": "/home",
|
||
"browser": "Chrome 120",
|
||
"os": "Mac OS X"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 网络事件格式
|
||
|
||
```json
|
||
{
|
||
"type": "network",
|
||
"level": "info",
|
||
"timestamp": 1704067200000,
|
||
"project_id": "1001",
|
||
|
||
"sub_type": "fetch",
|
||
"method": "GET",
|
||
"url": "/api/users",
|
||
"status_code": 200,
|
||
"duration": 123,
|
||
"success": true,
|
||
|
||
"tags": {
|
||
"route": "/home"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.3 Loki 查询示例
|
||
|
||
**查询某项目的错误总数（1小时内）**
|
||
```logql
|
||
count_over_time(
|
||
{project_id="1001", type="error"}[1h]
|
||
)
|
||
```
|
||
|
||
**查询某错误指纹的出现次数**
|
||
```logql
|
||
count_over_time(
|
||
{project_id="1001", fingerprint="a1b2c3d4"}[24h]
|
||
)
|
||
```
|
||
|
||
**查询某页面的 LCP P95**
|
||
```logql
|
||
quantile_over_time(
|
||
0.95,
|
||
{project_id="1001", type="performance"}
|
||
| json value=value
|
||
| metric="lcp"
|
||
| unwrap value
|
||
[5m]
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 三、MySQL 聚合表设计
|
||
|
||
### 3.1 错误聚合表
|
||
|
||
#### `error_stats_hourly` - 错误小时统计表
|
||
|
||
按错误指纹 + 项目 + 小时聚合，用于趋势图。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | BIGINT PK | 主键 |
|
||
| `project_id` | VARCHAR(64) | 项目 ID |
|
||
| `fingerprint` | VARCHAR(64) | 错误指纹 |
|
||
| `stat_hour` | DATETIME | 统计小时（整点） |
|
||
| `error_type` | VARCHAR(128) | 错误类型（TypeError 等） |
|
||
| `error_message` | VARCHAR(512) | 错误消息（截断） |
|
||
| `count` | INT | 发生次数 |
|
||
| `affected_users` | INT | 影响用户数（估算） |
|
||
| `first_seen` | DATETIME | 首次出现时间 |
|
||
| `last_seen` | DATETIME | 最后出现时间 |
|
||
| `created_at` | DATETIME | 创建时间 |
|
||
| `updated_at` | DATETIME | 更新时间 |
|
||
|
||
**索引**：
|
||
- `(project_id, stat_hour)` - 按项目+时间查询
|
||
- `(project_id, fingerprint, stat_hour)` - 按指纹+时间查询
|
||
- 唯一键：`(project_id, fingerprint, stat_hour)`
|
||
|
||
#### `error_issues` - 错误 Issue 表
|
||
|
||
按错误指纹聚合，用于错误列表管理。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | BIGINT PK | 主键 |
|
||
| `project_id` | VARCHAR(64) | 项目 ID |
|
||
| `fingerprint` | VARCHAR(64) UNIQUE | 错误指纹 |
|
||
| `error_type` | VARCHAR(128) | 错误类型 |
|
||
| `error_message` | TEXT | 错误消息 |
|
||
| `stack_trace` | TEXT | 堆栈摘要（前几帧） |
|
||
| `level` | VARCHAR(32) | 级别 |
|
||
| `platform` | VARCHAR(32) | 平台 |
|
||
| `total_count` | BIGINT | 总次数 |
|
||
| `today_count` | INT | 今日次数 |
|
||
| `yesterday_count` | INT | 昨日次数 |
|
||
| `affected_users` | INT | 影响用户数 |
|
||
| `status` | VARCHAR(32) | 状态：active / resolved / ignored |
|
||
| `assignee` | VARCHAR(64) | 处理人 |
|
||
| `first_seen` | DATETIME | 首次出现 |
|
||
| `last_seen` | DATETIME | 最后出现 |
|
||
| `created_at` | DATETIME | 创建时间 |
|
||
| `updated_at` | DATETIME | 更新时间 |
|
||
|
||
**状态流转**：
|
||
```
|
||
active ──→ resolved ──→ active（再次出现时复活）
|
||
│
|
||
└──→ ignored
|
||
```
|
||
|
||
### 3.2 性能统计表
|
||
|
||
#### `performance_stats_hourly` - 性能小时统计表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | BIGINT PK | 主键 |
|
||
| `project_id` | VARCHAR(64) | 项目 ID |
|
||
| `metric` | VARCHAR(32) | 指标名：lcp / fcp / cls / fid |
|
||
| `stat_hour` | DATETIME | 统计小时 |
|
||
| `page_url` | VARCHAR(256) | 页面 URL（可选，空=全部） |
|
||
| `sample_count` | INT | 样本数 |
|
||
| `p50` | DOUBLE | 中位数 |
|
||
| `p75` | DOUBLE | 75 分位 |
|
||
| `p90` | DOUBLE | 90 分位 |
|
||
| `p95` | DOUBLE | 95 分位 |
|
||
| `p99` | DOUBLE | 99 分位 |
|
||
| `avg` | DOUBLE | 平均值 |
|
||
| `good_rate` | DOUBLE | Good 比例（0-1） |
|
||
| `poor_rate` | DOUBLE | Poor 比例（0-1） |
|
||
| `created_at` | DATETIME | 创建时间 |
|
||
| `updated_at` | DATETIME | 更新时间 |
|
||
|
||
**索引**：
|
||
- `(project_id, metric, stat_hour)` - 主查询索引
|
||
- 唯一键：`(project_id, metric, stat_hour, page_url)`
|
||
|
||
#### `performance_stats_daily` - 性能日统计表
|
||
|
||
同上，按天聚合，用于长期趋势。
|
||
|
||
### 3.3 网络请求统计表
|
||
|
||
#### `network_stats_hourly` - 网络小时统计表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | BIGINT PK | 主键 |
|
||
| `project_id` | VARCHAR(64) | 项目 ID |
|
||
| `stat_hour` | DATETIME | 统计小时 |
|
||
| `method` | VARCHAR(16) | 请求方法 |
|
||
| `url_pattern` | VARCHAR(512) | URL 模式（归一化后） |
|
||
| `total_count` | INT | 总请求数 |
|
||
| `error_count` | INT | 错误数（4xx + 5xx） |
|
||
| `error_rate` | DOUBLE | 错误率 |
|
||
| `avg_duration` | DOUBLE | 平均耗时(ms) |
|
||
| `p50_duration` | DOUBLE | P50 耗时 |
|
||
| `p95_duration` | DOUBLE | P95 耗时 |
|
||
| `created_at` | DATETIME | 创建时间 |
|
||
|
||
**URL 归一化**：
|
||
- `/api/users/123` → `/api/users/:id`
|
||
- `/static/app.abc123.js` → `/static/app.[hash].js`
|
||
|
||
### 3.4 环境维度表
|
||
|
||
用于减少 Loki 中环境信息的冗余，配合 SDK 的字典编码和会话级共享使用。
|
||
|
||
#### `env_dimensions` - 环境维度表
|
||
|
||
每条唯一的环境组合只存 1 条，日志中通过 `env_id` 关联。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | BIGINT PK | 维度 ID |
|
||
| `project_id` | VARCHAR(64) | 项目 ID |
|
||
| `browser_name` | VARCHAR(32) | 浏览器名称 |
|
||
| `browser_version` | VARCHAR(32) | 浏览器主版本 |
|
||
| `os_name` | VARCHAR(32) | 操作系统 |
|
||
| `os_version` | VARCHAR(32) | OS 主版本 |
|
||
| `device_family` | VARCHAR(64) | 设备系列 |
|
||
| `device_model` | VARCHAR(64) | 设备型号 |
|
||
| `screen_resolution` | VARCHAR(32) | 屏幕分辨率 |
|
||
| `language` | VARCHAR(16) | 浏览器语言 |
|
||
| `hash` | VARCHAR(64) UNIQUE | 所有维度的哈希值，用于快速查找 |
|
||
| `first_seen` | DATETIME | 首次出现 |
|
||
| `last_seen` | DATETIME | 最后出现 |
|
||
| `count` | BIGINT | 出现次数（用于热度排序） |
|
||
|
||
**唯一键**：`(project_id, hash)`
|
||
|
||
**为什么用维度表？**
|
||
- Loki 的 JSON 日志里只存 `env_id`（1 个数字），不存完整的浏览器/OS/设备信息
|
||
- 每条日志节省 100-200 字节，百万级事件节省几十 GB
|
||
- 查询时 JOIN 维度表，或者直接用 Grafana 的变量查询
|
||
|
||
**服务端处理流程**：
|
||
```
|
||
事件到达 → 计算环境维度的 hash →
|
||
├─ 已存在 → 取 env_id，更新 last_seen + count
|
||
└─ 不存在 → 插入新记录，返回新 env_id
|
||
→ 日志写入 Loki，只带 env_id
|
||
```
|
||
|
||
#### `page_dimensions` - 页面维度表
|
||
|
||
同理，页面 URL 也可以做维度化：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | BIGINT PK | 页面 ID |
|
||
| `project_id` | VARCHAR(64) | 项目 ID |
|
||
| `url_pattern` | VARCHAR(512) | 归一化后的 URL 模式 |
|
||
| `path` | VARCHAR(512) | 路由路径 |
|
||
| `title` | VARCHAR(256) | 页面标题 |
|
||
| `hash` | VARCHAR(64) UNIQUE | 哈希 |
|
||
| `count` | BIGINT | 访问次数 |
|
||
|
||
#### `api_dimensions` - 接口维度表
|
||
|
||
网络请求的 URL、method 等也可以维度化，日志里只存 `api_id`：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | BIGINT PK | 接口 ID |
|
||
| `project_id` | VARCHAR(64) | 项目 ID |
|
||
| `method` | VARCHAR(16) | 请求方法（GET/POST/...） |
|
||
| `url_pattern` | VARCHAR(512) | 归一化后的 URL 模式 |
|
||
| `domain` | VARCHAR(128) | 域名 |
|
||
| `hash` | VARCHAR(64) UNIQUE | method + url_pattern 的哈希 |
|
||
| `total_count` | BIGINT | 总请求数 |
|
||
| `error_count` | BIGINT | 错误数 |
|
||
| `avg_duration` | DOUBLE | 平均耗时 |
|
||
| `last_seen` | DATETIME | 最后出现时间 |
|
||
|
||
**为什么要做接口维度化？**
|
||
- 日志里只存 `api_id`（8 字节），不用存完整 URL
|
||
- URL 归一化后，同一路由的不同参数只会产生 1 条维度记录
|
||
- 按接口统计错误率、耗时等指标时，直接 JOIN 维度表即可
|
||
|
||
### 3.5 项目配置表
|
||
|
||
#### `projects` - 项目表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | VARCHAR(64) PK | 内部 ID（proj_xxx） |
|
||
| `project_id` | VARCHAR(32) UNIQUE | Sentry 项目 ID（纯数字） |
|
||
| `public_key` | VARCHAR(64) | 公钥（默认=内部 ID） |
|
||
| `name` | VARCHAR(128) | 项目名称 |
|
||
| `platform` | VARCHAR(32) | 平台 |
|
||
| `environment` | VARCHAR(32) | 默认环境 |
|
||
| `description` | TEXT | 描述 |
|
||
| `status` | VARCHAR(32) | 状态：active / disabled |
|
||
| `rate_limit` | INT | 速率限制（事件/天） |
|
||
| `sample_rate` | DOUBLE | 采样率（0-1） |
|
||
| `created_at` | DATETIME | 创建时间 |
|
||
| `updated_at` | DATETIME | 更新时间 |
|
||
|
||
#### `alert_rules` - 告警规则表
|
||
|
||
见告警引擎设计文档。
|
||
|
||
---
|
||
|
||
## 四、聚合任务设计
|
||
|
||
### 4.1 聚合方式
|
||
|
||
| 方式 | 实时性 | 复杂度 | 适用场景 |
|
||
|------|--------|--------|----------|
|
||
| **实时增量聚合** | 秒级 | 中 | 错误计数、Issue 更新 |
|
||
| **定时批量聚合** | 分钟级 | 低 | 性能分位数、小时统计 |
|
||
| **离线重算** | 天级 | 高 | 数据修正、历史回刷 |
|
||
|
||
### 4.2 实时增量聚合（错误计数）
|
||
|
||
每次事件处理时，直接更新 MySQL：
|
||
|
||
```sql
|
||
INSERT INTO error_issues
|
||
(project_id, fingerprint, error_type, error_message,
|
||
total_count, today_count, last_seen, first_seen, status)
|
||
VALUES
|
||
(?, ?, ?, ?, 1, 1, NOW(), NOW(), 'active')
|
||
ON DUPLICATE KEY UPDATE
|
||
total_count = total_count + 1,
|
||
today_count = today_count + 1,
|
||
last_seen = NOW(),
|
||
status = CASE WHEN status = 'resolved' THEN 'active' ELSE status END;
|
||
```
|
||
|
||
**优点**：实时性好，数据立刻可见
|
||
**缺点**：高并发下 MySQL 压力大
|
||
|
||
**优化**：
|
||
- 内存中先做 1 秒级别的微批聚合，再批量写 MySQL
|
||
- 使用 Redis 做计数缓冲，定期刷入 MySQL
|
||
|
||
### 4.3 定时批量聚合（性能统计）
|
||
|
||
使用 Cron 定时任务，每 5 分钟从 Loki 拉取数据聚合：
|
||
|
||
```
|
||
每 5 分钟执行：
|
||
1. 从 Loki 查询过去 5 分钟的性能事件
|
||
2. 按 project + metric + 页面 分组
|
||
3. 计算 P50/P90/P95/avg 等指标
|
||
4. 写入 performance_stats_hourly 表
|
||
```
|
||
|
||
**为什么用定时任务而不是实时？**
|
||
- 性能指标不需要秒级实时
|
||
- 分位数计算需要一定数据量才准确
|
||
- 定时批量更省资源
|
||
|
||
### 4.4 数据过期与归档
|
||
|
||
#### Loki 数据过期
|
||
|
||
通过 Loki 的 `retention` 配置自动删除：
|
||
|
||
```yaml
|
||
limits_config:
|
||
retention_period: 168h # 7 天
|
||
```
|
||
|
||
#### MySQL 数据过期
|
||
|
||
- 小时统计表：保留 30 天
|
||
- 日统计表：保留 1 年
|
||
- 错误 Issue 表：永久保留（只存聚合数据，量很小）
|
||
|
||
定时任务每天凌晨清理过期数据。
|
||
|
||
---
|
||
|
||
## 五、数据迁移与兼容
|
||
|
||
### 5.1 当前状态
|
||
|
||
目前项目使用 JSON 文件存储项目配置，Loki 存储原始日志，没有 MySQL 聚合层。
|
||
|
||
### 5.2 演进路径
|
||
|
||
**阶段 1：JSON → SQLite（单机版）**
|
||
- 零依赖，开箱即用
|
||
- 适合个人项目、小团队
|
||
- 单节点足够
|
||
|
||
**阶段 2：SQLite → MySQL（生产版）**
|
||
- 支持并发
|
||
- 性能更好
|
||
- 适合多项目、中大型团队
|
||
|
||
**阶段 3：增加 ClickHouse（大规模）**
|
||
- 亿级数据量
|
||
- 复杂分析查询
|
||
- 一般不需要
|
||
|
||
---
|
||
|
||
## 六、Grafana 数据源配置
|
||
|
||
### 6.1 Loki 数据源
|
||
|
||
- URL: `http://loki:3100`
|
||
- 开启 JSON 解析
|
||
- 配置 Derived fields（从日志跳转到追踪）
|
||
|
||
### 6.2 MySQL 数据源
|
||
|
||
- 用于展示聚合数据（性能趋势、错误趋势）
|
||
- 比 Loki 查询更稳定、更快
|
||
|
||
---
|
||
|
||
## 七、数据安全
|
||
|
||
### 7.1 数据脱敏
|
||
|
||
- 入库前脱敏：SDK 端 + 服务端双重脱敏
|
||
- 查询时脱敏：敏感字段查询结果自动打码
|
||
- 导出时脱敏：导出数据默认脱敏
|
||
|
||
### 7.2 数据隔离
|
||
|
||
- 项目间完全隔离（通过 project_id label）
|
||
- 查询时强制带 project_id 条件
|
||
- 管理后台有项目权限控制
|
||
|
||
### 7.3 数据备份
|
||
|
||
- MySQL：每日全量备份 + binlog 增量备份
|
||
- Loki：定期快照到对象存储
|
||
- 配置文件：Git 版本管理
|