# 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`