83 lines
3.2 KiB
Markdown
83 lines
3.2 KiB
Markdown
# fault-log-analyzer
|
||
|
||
主机监控系统（HMS）故障日志捕获与分析模块。
|
||
|
||
## 功能
|
||
|
||
1. **故障日志捕获管道**：消费 `logs.raw`，按级别/关键字/正则过滤，结构化解析，
|
||
打标后写入 `logs.fault` 与 Elasticsearch（`hms-fault-log-{yyyy.MM}`）。
|
||
2. **故障日志归类**：特征提取（模板化 + TF-IDF）→ 相似聚类（DBSCAN / 纯 Python 后端）
|
||
→ 映射到 `fault_type`。
|
||
3. **根因分析**：时间/主机关联指标事件 + 指标-故障规则库 + trace 关联，产出
|
||
`root_cause`（含 evidence 与 confidence）。
|
||
4. **REST API**：故障日志查询、根因查询、故障类型/过滤规则管理接口。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
src/fault_log_analyzer/
|
||
config.py 配置模型与环境变量加载
|
||
models.py 数据模型（FaultLog / RootCause / FaultType / ...）
|
||
parser.py 日志结构化解析与模板化
|
||
filters.py 故障过滤规则
|
||
fingerprint.py MinHash 指纹与去重
|
||
cluster.py TF-IDF 特征 + DBSCAN 聚类
|
||
classifier.py 簇 -> fault_type 归类
|
||
root_cause.py 根因分析
|
||
storage.py 存储抽象 + 内存实现（测试/离线）
|
||
integrations.py 可选真实后端（Kafka/ES/MySQL/Redis）
|
||
pipeline.py 故障捕获管道
|
||
workers.py 聚类 / 根因分析 worker
|
||
api.py REST API（标准库 http.server 实现）
|
||
__main__.py CLI 入口
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 安装（核心零依赖，可选依赖见 requirements.txt）
|
||
pip install -e .
|
||
|
||
# 运行单元测试（131 个测试用例）
|
||
python -m unittest discover -s tests -v
|
||
|
||
# 启动服务（内存存储，便于本地验证）
|
||
python -m fault_log_analyzer --storage memory --api-host 127.0.0.1 --api-port 8080
|
||
|
||
# 健康检查
|
||
curl http://127.0.0.1:8080/healthz
|
||
curl http://127.0.0.1:8080/api/v1/fault-logs
|
||
```
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
python -m unittest discover -s tests -v
|
||
# Ran 131 tests ... OK
|
||
```
|
||
|
||
测试覆盖：配置加载、数据模型、日志解析/模板化、故障过滤规则、MinHash 指纹去重、
|
||
TF-IDF/DBSCAN 聚类、故障归类、根因分析、捕获管道、聚类/根因 worker、REST API、
|
||
以及 Kafka/Elasticsearch/MySQL/Redis 可选后端适配器（未安装依赖时的回退行为与索引名）。
|
||
|
||
## 环境变量（生产）
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|---|---|---|
|
||
| `KAFKA_BOOTSTRAP_SERVERS` | `localhost:9092` | Kafka 地址 |
|
||
| `KAFKA_GROUP_ID` | `fault-log-analyzer` | 消费者组 |
|
||
| `KAFKA_LOGS_RAW_TOPIC` | `logs.raw` | 原始日志 topic |
|
||
| `KAFKA_LOGS_FAULT_TOPIC` | `logs.fault` | 故障日志 topic |
|
||
| `ES_HOSTS` | `http://localhost:9200` | ES 地址（逗号分隔） |
|
||
| `MYSQL_HOST` / `MYSQL_PORT` / `MYSQL_USER` / `MYSQL_PASSWORD` / `MYSQL_DB` | localhost | MySQL 连接 |
|
||
| `REDIS_URL` | `redis://localhost:6379/0` | Redis 地址 |
|
||
| `CLUSTER_EPS` | `0.75` | DBSCAN eps（余弦距离） |
|
||
| `CLUSTER_MIN_SAMPLES` | `5` | DBSCAN min_samples |
|
||
| `ROOT_CAUSE_WINDOW_MINUTES` | `5` | 根因分析时间窗口 |
|
||
|
||
## 开发说明
|
||
|
||
- 模块状态：`modules/fault-log-analyzer.md`
|
||
- 开发说明：`docs/02-develop/fault-log-analyzer-dev-notes.md`
|
||
- 设计依据：`docs/01-design/architecture.md`（5.3）、`database-design.md`、`api-design.md`
|