Skip to content

Commit e0cab18

Browse files
acd19mlacd19ml
committed
doc(Metrics&Alert): 更新修改监控/告警处理模块README,重新组织内部功能划分
1 parent 413ff4a commit e0cab18

File tree

1 file changed

+123
-141
lines changed

1 file changed

+123
-141
lines changed

‎internal/alerting/README.md‎

Lines changed: 123 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -1,163 +1,145 @@
1-
监控/告警处理模块（Alerting）
2-
3-
目标
4-
- 统一接收、聚合与去重来自 Prometheus/ES/第三方的告警事件
5-
- 将事件归并为告警问题（Issue），支持生命周期/状态机管理
6-
- 结合服务元数据计算影响面，产出最终告警等级（P0/P1/P2/Warning）
7-
- 支持自动/半自动治愈与回填评论，形成可追溯处置记录
8-
- 提供查询、检索与统计 API，服务控制台与自动化流程
9-
10-
模块边界
11-
- 输入：告警事件流（Webhook/轮询）、指标查询、服务元数据
12-
- 输出：告警问题（Issue）数据、评论记录、通知、治愈执行
13-
- 不做：指标采集、底层存储运维（交由公共组件）
14-
15-
目录结构（Hexagonal/Clean）
16-
internal/alerting/
17-
- domain/ 领域模型与端口（接口）
18-
- types.go Level/Issue/Comment/Event 等
19-
- ports.go IssueRepository/RuleCalculator/Notifier/Healer 等
20-
- usecase/ 应用服务（聚合、状态机、等级计算、治愈编排）
21-
- service.go New(repo, rules, notifiers, healers)
22-
- adapter/ 适配器：传输/存储/规则/通知/治愈/接入
23-
- httpapi/ HTTP 路由与 DTO
24-
- repository/memory/ 内存仓储（示例）
25-
- rules/default/ 默认等级计算器
26-
- notifier/feishu/ 飞书通知（示例）
27-
- ingest/prometheus/ Prometheus 事件接入（示例）
28-
- api/ 便捷装配（示例项目直接调用）
29-
- scheduler/ （可选）体检/巡检定时任务
30-
- README.md 本文档
31-
32-
数据模型（MySQL）
1+
好的 ✅
2+
我帮你整理一个完整的 README 文档，包括模块说明、目录结构、API 示例、数据库设计、以及后续扩展说明。这样团队成员在接手或协作时能快速上手。
3+
4+
⸻
5+
6+
Monitoring & Alerting Service
7+
8+
📌 概述
9+
10+
本服务为 监控 / 告警处理模块，用于统一接收、存储、处理、恢复和记录告警信息。它提供了标准化的 API 接口，支持告警生命周期管理、规则调整、告警元数据管理、周期性健康检查、告警等级计算，以及自动化治愈行为处理。
11+
12+
目标：
13+
• 提高告警处理自动化程度
14+
• 支持 AI/系统/人工协同处理
15+
• 为平台提供可追踪的告警问题管理与分析
16+
17+
⸻
18+
19+
📂 目录结构
20+
21+
alerting/
22+
├── api/ # API 接口层，定义 HTTP handler
23+
├── database/ # 数据库相关定义和 migration
24+
├── model/ # 数据模型 (ORM/DTO)
25+
├── service/ # 核心业务逻辑
26+
│ ├── receiver/ # 告警接收与处理
27+
│ ├── rules/ # 告警规则调整
28+
│ ├── metadata/ # 监控与告警元数据
29+
│ ├── healthcheck/ # 周期体检任务
30+
│ ├── severity/ # 告警等级计算
31+
│ └── remediation/ # 自动化治愈行为
32+
└── README.md # 项目说明文档
33+
34+
35+
⸻
36+
37+
🗄 数据库设计
38+
3339
1) alert_issues（告警问题表）
34-
- 主键：id（字符串或自增，推荐字符串以便跨源唯一）
35-
- 字段：
36-
- state：问题状态（Open/Closed）
37-
- level：告警等级（P0/P1/P2/Warning）
38-
- alertState：处理状态（InProcessing/AutoRestored/Restored）
39-
- title：标题
40-
- label：JSON（单一标签对象 {key,value}）
41-
- alertSince：DATETIME（首次告警时间）
42-
- json：JSON 扩展（原始维度/链接等）
43-
44-
2) alert_issue_comments（告警问题评论表）
45-
- 主键：无单独主键，按业务以 issueID+createAt 唯一（或可加自增列）
46-
- issueID：外键关联 alert_issues.id
47-
- createAt：DATETIME
48-
- content：TEXT（Markdown，记录AI/系统/人工动作）
49-
50-
建表示例
51-
```sql
52-
CREATE TABLE alert_issues (
53-
id VARCHAR(64) PRIMARY KEY,
54-
state VARCHAR(16) NOT NULL,
55-
level VARCHAR(16) NOT NULL,
56-
alertState VARCHAR(32) NOT NULL,
57-
title VARCHAR(255) NOT NULL,
58-
label JSON NULL,
59-
alertSince DATETIME(3) NOT NULL,
60-
json JSON NULL,
61-
KEY idx_state_level (state, level),
62-
KEY idx_alert_since (alertSince)
63-
);
64-
65-
CREATE TABLE alert_issue_comments (
66-
issueID VARCHAR(64) NOT NULL,
67-
createAt DATETIME(3) NOT NULL,
68-
content MEDIUMTEXT NOT NULL,
69-
KEY idx_issue (issueID),
70-
CONSTRAINT fk_issue FOREIGN KEY (issueID) REFERENCES alert_issues(id)
71-
);
72-
```
73-
74-
状态机
75-
- Issue.state：Open → Closed（单向闭环）
76-
- Issue.alertState：
77-
- InProcessing（处理中）
78-
- AutoRestored（自然恢复）
79-
- Restored（已恢复）
80-
81-
告警等级计算
82-
- 输入：原始告警等级（来自源头）+ 服务影响面（流量、租户数、区域、核心度）
83-
- 输出：最终 level（P0/P1/P2/Warning）
84-
- 计算器放置于 `rules/`，通过接口可热插拔与单元测试
85-
86-
API 接口
87-
1) 列表
88-
GET /v1/issues?start=xxx&limit=10&state=Closed|Open
89-
响应：
40+
41+
字段名 类型 说明
42+
id varchar(255) PK 告警 issue ID
43+
state enum(Closed, Open) 告警状态
44+
level varchar(32) 告警等级，如 P0/P1/P2/Warning
45+
alertState enum(Restored, AutoRestored, InProcessing) 告警处理状态
46+
title varchar(255) 告警标题
47+
label json 标签，格式：[{key, value}]
48+
alertSince timestamp 告警发生时间
49+
50+
51+
⸻
52+
53+
2) alert_issue_comments（告警评论表）
54+
55+
字段名 类型 说明
56+
issueID varchar(255) FK 对应 alert_issues.id
57+
createAt timestamp 评论创建时间
58+
content text Markdown 格式，记录 AI/系统/人工动作
59+
60+
61+
⸻
62+
63+
🌐 API 接口
64+
65+
1. 获取告警列表
66+
67+
GET /v1/issues?start=xxxx&limit=10[&state=Closed]
68+
69+
Response
70+
9071
{
91-
"items": [
92-
{
93-
"id": "xxx", // 告警 issue ID
94-
"state": "Closed", // 告警条目的状态。Closed处理完成、Open处理中
95-
"level": "P0", // 枚举值：P0严重、P1重要、P2、Warning需要关注但不是线上异常
96-
"alertState": "Restored", // 告警处理状态。Restored 已恢复、AutoRestored 系统自动恢复、InProcessing 处理中
97-
"title": "yzh S3APIV2s3apiv2.putobject 0_64K上传响应时间95值:50012ms > 450ms", // 告警标题
98-
"labels": [
99-
{
100-
"key": "api",
101-
"value: "s3apiv2.putobject"
102-
},
103-
{
104-
"key": "idc",
105-
"value": "yzh"
106-
}
107-
],
108-
"alertSince": "2025-05-05 11:00:00.0000Z"
109-
}
110-
]
72+
"items": [
73+
{
74+
"id": "xxx",
75+
"state": "Closed",
76+
"level": "P0",
77+
"alertState": "Restored",
78+
"title": "yzh S3APIV2s3apiv2.putobject 0_64K上传响应时间95值:50012ms > 450ms",
79+
"labels": [
80+
{"key": "api", "value": "s3apiv2.putobject"},
81+
{"key": "idc", "value": "yzh"}
82+
],
83+
"alertSince": "2025-05-05 11:00:00.0000Z"
84+
}
85+
]
11186
}
11287

113-
2) 详情
88+
89+
⸻
90+
91+
2. 获取告警详情
92+
11493
GET /v1/issues/:issueID
115-
响应：
94+
95+
Response
96+
11697
{
11798
"id": "xxx",
11899
"state": "Closed",
119100
"level": "P0",
120101
"alertState": "Restored",
121-
"title": "...",
122-
"label": {"key":"api","value":"s3apiv2.putobject"},
123-
"alertSince": "2025-05-05T11:00:00Z",
124-
"json": {"k":"v"},
102+
"title": "yzh S3APIV2s3apiv2.putobject 0_64K上传响应时间95值:50012ms > 450ms",
103+
"labels": [
104+
{"key": "api", "value": "s3apiv2.putobject"},
105+
{"key": "idc", "value": "yzh"}
106+
],
107+
"alertSince": "2025-05-05 11:00:00.0000Z",
125108
"comments": [
126-
{"issueID": "xxx", "createAt": "2024-01-03T03:00:00Z", "content": "markdown content"}
109+
{
110+
"createAt": "2024-01-03T03:00:00Z",
111+
"content": "markdown content"
112+
}
127113
]
128114
}
129115

130-
4) 手动关闭（标记恢复正常）
131-
POST /v1/issues/:issueID/close
132-
响应：200
133116

117+
⸻
134118

135-
摄入（Ingress）
136-
- Prometheus Webhook：/v1/ingest/prometheus
137-
- Elastic/Logs：定制 handler 于 `ingest/`
138-
- 每个接入负责标准化为内部 Event，交由 service 层聚合
119+
⚙️ Service 模块功能
139120

140-
治愈（Healing）
141-
- `healing/` 定义动作（如重启、扩容、清缓存），由编排器串联
142-
- 执行结果写入 `alert_issue_comments`，并可更新 `alertState`
121+
1. receiver/ 告警接收与处理
122+
• 统一接收外部监控系统告警（如 Prometheus、Grafana、内部 SDK）
123+
• 将原始告警写入数据库
124+
• 触发告警处理流程
143125

144-
通知（Notifier）
145-
- 在 state 变化或等级升级时触发
146-
- 通过 `notifier/` 适配钉钉/飞书/邮件，支持静默窗口与去重
126+
2. rules/ 告警规则调整
127+
• 支持动态调整告警触发规则（如阈值、持续时间、条件组合）
128+
• 提供规则存储、加载与热更新
147129

148-
定时体检（Scheduler）
149-
- 周期巡检 SLO/关键链路，将异常转化为 Issue 流入统一闭环
130+
3. metadata/ 监控与告警元数据
131+
• 存储告警相关上下文（服务信息、监控指标、依赖关系）
132+
• 便于查询与告警溯源
150133

151-
安全与审计
152-
- API 走网关鉴权；重要动作（关闭/忽略/治愈）记录评论与审计日志
134+
4. healthcheck/ 周期体检任务
135+
• 定时扫描核心服务，生成健康报告
136+
• 与告警系统集成，主动发现潜在风险
153137

154-
代码组织建议（Go）
155-
- domain：领域模型与端口接口；无外部依赖
156-
- usecase：只依赖 domain；通过端口调用适配器
157-
- adapter：实现端口；彼此解耦，可替换
158-
- api：http 仅做 DTO/编排，依赖 usecase
138+
5. severity/ 告警等级计算
139+
• 综合 告警原始等级 + 影响范围（服务/用户/地区）
140+
• 动态调整告警优先级（如 P2 → P1）
159141

160-
测试建议
161-
- rules：基于样例数据的表驱动测试
162-
- service：状态机与聚合流程的单元测试
163-
- api：handler 层的端到端（通过 fake service）
142+
6. remediation/ 自动化治愈行为
143+
• 提供预定义自动修复动作（重启服务、扩容、流量切换）
144+
• 支持 AI 推荐修复方案
145+
• 记录执行结果到 alert_issue_comments

0 commit comments

Comments
 (0)