Skip to content

Commit d51183e

Browse files
acd19mlacd19ml
committed
doc(Metrics&Alert):补充api、数据表文档
1 parent cbf1a10 commit d51183e

File tree

2 files changed

+323
-0
lines changed

2 files changed

+323
-0
lines changed

‎docs/alerting/api.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# API 文档 - Monitoring & Alerting Service
2+
3+
## 概述
4+
5+
本文档描述了监控告警服务的 RESTful API 接口，包括告警列表查询、详情获取等核心功能。
6+
7+
## 基础信息
8+
9+
- **Base URL**: `/v1`
10+
- **Content-Type**: `application/json`
11+
- **认证方式**: Bearer Token（具体实现待定）
12+
13+
## 接口列表
14+
15+
### 1. 获取告警列表
16+
17+
获取告警问题列表，支持分页和状态筛选。
18+
19+
**请求：**
20+
```http
21+
GET /v1/issues?start={start}&limit={limit}[&state={state}]
22+
```
23+
24+
**查询参数：**
25+
26+
| 参数名 | 类型 | 必填 | 说明 |
27+
|--------|------|------|------|
28+
| start | string | 是 | 分页起始位置标识 |
29+
| limit | integer | 是 | 每页返回数量，建议范围：1-100 |
30+
| state | string | 否 | 问题状态筛选：`Open`、`Closed` |
31+
32+
**响应示例：**
33+
```json
34+
{
35+
"items": [
36+
{
37+
"id": "issue_20250505_001",
38+
"state": "Closed",
39+
"level": "P0",
40+
"alertState": "Restored",
41+
"title": "yzh S3APIV2s3apiv2.putobject 0_64K上传响应时间95值:50012ms > 450ms",
42+
"labels": [
43+
{"key": "api", "value": "s3apiv2.putobject"},
44+
{"key": "idc", "value": "yzh"},
45+
{"key": "service", "value": "s3api"}
46+
],
47+
"alertSince": "2025-05-05T11:00:00.000Z"
48+
}
49+
],
50+
"pagination": {
51+
"nextStart": "issue_20250505_002",
52+
"hasMore": true
53+
}
54+
}
55+
```
56+
57+
**状态码：**
58+
- `200 OK`: 成功获取列表
59+
- `400 Bad Request`: 参数错误
60+
- `401 Unauthorized`: 认证失败
61+
- `500 Internal Server Error`: 服务器内部错误
62+
63+
### 2. 获取告警详情
64+
65+
获取指定告警问题的详细信息，包括处理历史。
66+
67+
**请求：**
68+
```http
69+
GET /v1/issues/{issueID}
70+
```
71+
72+
**路径参数：**
73+
74+
| 参数名 | 类型 | 必填 | 说明 |
75+
|--------|------|------|------|
76+
| issueID | string | 是 | 告警问题ID |
77+
78+
**响应示例：**
79+
```json
80+
{
81+
"id": "issue_20250505_001",
82+
"state": "Closed",
83+
"level": "P0",
84+
"alertState": "Restored",
85+
"title": "yzh S3APIV2s3apiv2.putobject 0_64K上传响应时间95值:50012ms > 450ms",
86+
"labels": [
87+
{"key": "api", "value": "s3apiv2.putobject"},
88+
{"key": "idc", "value": "yzh"},
89+
{"key": "service", "value": "s3api"}
90+
],
91+
"alertSince": "2025-05-05T11:00:00.000Z",
92+
"resolvedAt": "2025-05-05T11:15:00.000Z",
93+
"comments": [
94+
{
95+
"createAt": "2025-05-05T11:00:30.000Z",
96+
"content": "## 自动分析\n\n检测到 S3 API 响应时间异常，可能原因：\n- 后端存储负载过高\n- 网络延迟增加\n\n## 建议处理\n1. 检查存储节点状态\n2. 分析网络监控数据"
97+
},
98+
{
99+
"createAt": "2025-05-05T11:05:00.000Z",
100+
"content": "## 自动治愈开始\n\n执行治愈策略：重启相关服务实例"
101+
},
102+
{
103+
"createAt": "2025-05-05T11:15:00.000Z",
104+
"content": "## 问题已解决\n\n响应时间恢复正常，告警自动关闭"
105+
}
106+
]
107+
}
108+
```
109+
110+
**状态码：**
111+
- `200 OK`: 成功获取详情
112+
- `404 Not Found`: 告警问题不存在
113+
- `401 Unauthorized`: 认证失败
114+
- `500 Internal Server Error`: 服务器内部错误
115+
116+
## 数据模型
117+
118+
### AlertIssue 对象
119+
120+
| 字段名 | 类型 | 说明 |
121+
|--------|------|------|
122+
| id | string | 告警问题唯一标识 |
123+
| state | string | 问题状态：`Open`、`Closed` |
124+
| level | string | 告警等级：`P0`、`P1`、`P2`、`Warning` |
125+
| alertState | string | 处理状态：`Restored`、`AutoRestored`、`InProcessing` |
126+
| title | string | 告警标题描述 |
127+
| labels | Label[] | 标签数组 |
128+
| alertSince | string | 告警发生时间（ISO 8601格式） |
129+
| resolvedAt | string | 问题解决时间（仅在已解决时存在） |
130+
| comments | Comment[] | 处理评论列表（仅详情接口返回） |
131+
132+
### Label 对象
133+
134+
| 字段名 | 类型 | 说明 |
135+
|--------|------|------|
136+
| key | string | 标签键 |
137+
| value | string | 标签值 |
138+
139+
### Comment 对象
140+
141+
| 字段名 | 类型 | 说明 |
142+
|--------|------|------|
143+
| createAt | string | 评论创建时间（ISO 8601格式） |
144+
| content | string | 评论内容（Markdown格式） |
145+
146+
## 错误响应
147+
148+
所有接口在出错时返回统一的错误格式：
149+
150+
```json
151+
{
152+
"error": {
153+
"code": "INVALID_PARAMETER",
154+
"message": "参数 limit 必须在 1-100 范围内",
155+
"details": {
156+
"field": "limit",
157+
"value": "150"
158+
}
159+
}
160+
}
161+
```
162+
163+
### 错误代码
164+
165+
| 错误代码 | 说明 |
166+
|----------|------|
167+
| INVALID_PARAMETER | 请求参数错误 |
168+
| UNAUTHORIZED | 认证失败 |
169+
| FORBIDDEN | 权限不足 |
170+
| NOT_FOUND | 资源不存在 |
171+
| INTERNAL_ERROR | 服务器内部错误 |
172+
173+
## 使用示例
174+
175+
### curl 示例
176+
177+
```bash
178+
# 获取告警列表
179+
curl -X GET "https://api.example.com/v1/issues?start=0&limit=10&state=Open" \
180+
-H "Authorization: Bearer YOUR_TOKEN" \
181+
-H "Content-Type: application/json"
182+
183+
# 获取告警详情
184+
curl -X GET "https://api.example.com/v1/issues/issue_20250505_001" \
185+
-H "Authorization: Bearer YOUR_TOKEN" \
186+
-H "Content-Type: application/json"
187+
```
188+
189+
### JavaScript 示例
190+
191+
```javascript
192+
// 获取告警列表
193+
const response = await fetch('/v1/issues?start=0&limit=10', {
194+
headers: {
195+
'Authorization': 'Bearer ' + token,
196+
'Content-Type': 'application/json'
197+
}
198+
});
199+
const data = await response.json();
200+
201+
// 获取告警详情
202+
const detailResponse = await fetch(`/v1/issues/${issueId}`, {
203+
headers: {
204+
'Authorization': 'Bearer ' + token,
205+
'Content-Type': 'application/json'
206+
}
207+
});
208+
const detail = await detailResponse.json();
209+
```
210+
211+
## 版本历史
212+
213+
- **v1.0** (2025-09-11): 初始版本，支持基础的告警列表和详情查询

‎docs/alerting/database-design.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# 数据库设计 - Monitoring & Alerting Service
2+
3+
## 概述
4+
5+
本文档描述了监控告警服务的数据库表结构设计，包括告警问题、评论、模版和服务元数据等核心数据模型。
6+
7+
## 数据表设计
8+
9+
### 1) alert_issues（告警问题表）
10+
11+
存储告警问题的主要信息。
12+
13+
| 字段名 | 类型 | 说明 |
14+
|--------|------|------|
15+
| id | varchar(255) PK | 告警 issue ID |
16+
| state | enum(Closed, Open) | 问题状态 |
17+
| level | varchar(32) | 告警等级：P0/P1/P2/Warning |
18+
| alertState | enum(Restored, AutoRestored, InProcessing) | 处理状态 |
19+
| title | varchar(255) | 告警标题 |
20+
| label | json | 标签，格式：[{key, value}] |
21+
| alertSince | timestamp | 告警发生时间 |
22+
23+
**索引建议：**
24+
- PRIMARY KEY: `id`
25+
- INDEX: `state, level, alertSince`
26+
- INDEX: `alertState, alertSince`
27+
28+
### 2) alert_issue_comments（告警评论表）
29+
30+
存储告警问题的处理记录和评论。
31+
32+
| 字段名 | 类型 | 说明 |
33+
|--------|------|------|
34+
| issueID | varchar(255) FK | 对应 alert_issues.id |
35+
| createAt | timestamp | 评论创建时间 |
36+
| content | text | Markdown 格式，记录 AI/系统/人工动作 |
37+
38+
**索引建议：**
39+
- PRIMARY KEY: `issueID, createAt`
40+
- FOREIGN KEY: `issueID` REFERENCES `alert_issues(id)`
41+
42+
### 3) alert_templates（告警模版表）
43+
44+
存储告警规则模版，支持占位符参数化。
45+
46+
| 字段名 | 类型 | 说明 |
47+
|--------|------|------|
48+
| id | varchar(255) PK | 模版ID |
49+
| expr | text | 表达式，含占位符（如 {apitime_threshold}） |
50+
| level | varchar(32) | 默认告警等级 |
51+
52+
**索引建议：**
53+
- PRIMARY KEY: `id`
54+
55+
### 4) alert_service_metadata（服务元数据表）
56+
57+
存储服务特定的配置参数，用于模版参数化。
58+
59+
| 字段名 | 类型 | 说明 |
60+
|--------|------|------|
61+
| service | varchar(255) | 服务名 |
62+
| key | varchar(255) | 参数名（如 apitime_threshold） |
63+
| value | varchar(255) | 参数值 |
64+
65+
**索引建议：**
66+
- PRIMARY KEY: `service, key`
67+
- INDEX: `service`
68+
69+
## 数据关系
70+
71+
```mermaid
72+
erDiagram
73+
alert_issues ||--o{ alert_issue_comments : "has comments"
74+
alert_templates ||--o{ alert_service_metadata : "uses metadata"
75+
76+
alert_issues {
77+
varchar id PK
78+
enum state
79+
varchar level
80+
enum alertState
81+
varchar title
82+
json label
83+
timestamp alertSince
84+
}
85+
86+
alert_issue_comments {
87+
varchar issueID FK
88+
timestamp createAt
89+
text content
90+
}
91+
92+
alert_templates {
93+
varchar id PK
94+
text expr
95+
varchar level
96+
}
97+
98+
alert_service_metadata {
99+
varchar service PK
100+
varchar key PK
101+
varchar value
102+
}
103+
```
104+
105+
## 数据流转
106+
107+
1. **告警模版** + **服务元数据** → 生成实际告警规则
108+
2. 规则触发时创建 **告警问题记录**
109+
3. 处理过程中在 **评论表** 记录操作日志
110+
4. 问题解决后更新状态为 `Closed`

0 commit comments

Comments
 (0)