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 入口

快速开始

# 安装（核心零依赖，可选依赖见 requirements.txt）
pip install -e .

# 运行单元测试（133 个测试用例）
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

测试

python -m unittest discover -s tests -v
# Ran 133 tests ... OK

测试覆盖：配置加载、数据模型、日志解析/模板化、故障过滤规则、MinHash 指纹去重、 TF-IDF/DBSCAN 聚类、故障归类、根因分析（含 naive/aware 时间归一化）、捕获管道、 聚类/根因 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