历史与趋势

持久化存储与历史趋势分析（v0.5.0+）

SQLite 持久化

所有分析结果自动持久化到本地 SQLite 数据库（better-sqlite3）。数据库在首次使用时懒加载，采用 WAL 模式以获得最佳读取性能。

数据库位置：由 SQLITE_PATH 环境变量控制（默认：./storage/kafka-analyzer.db）

如果存储目录不可写或 better-sqlite3 加载失败，系统优雅降级——分析继续进行但不持久化。

存储的数据

表	说明
analysis_records	每次分析运行的摘要统计
anomaly_details	关联到分析记录的异常明细
lag_snapshots	每次 get_lag 的结果快照
baselines	自动（7 天滚动均值）和手动基线

事件驱动架构

持久化和基线更新通过内部 EventEmitter 与分析流水线解耦：

analyze_log 完成 → emit('analysis:completed')
    ├─→ 持久化监听器 → 写入 SQLite → emit('analysis:persisted')
    └─→ 基线监听器 → 更新自动基线（7 天均值）

get_lag 完成 → emit('lag:completed')
    └─→ 持久化监听器 → 写入 lag_snapshots

监听器错误隔离——失败的监听器只记日志，不会中断主分析流程。

异常倍数检测

分析检测到异常时，系统自动将当前值与存储的基线对比。如果值**≥ 基线 2 倍**，异常会收到倍数元数据标注：

⚠️ lag_spike [P0] consumer
   3 partitions with lag > 10000 detected
   🔺 比基线多 3.5 倍（基线: 2857, 当前: 10000, 来源: auto-7d）

这在返回结果前同步完成——无需额外工具调用。

MCP 工具

query_history

查询历史分析记录，支持过滤。

参数：

参数	类型	说明
from	string	起始时间 ISO 8601（默认：7 天前）
to	string	截止时间 ISO 8601（默认：now）
source	string	按来源过滤：paste / file / exporter / loki
cluster	string	按集群过滤
limit	number	返回条数（默认：50，最大：200）

compare_trend

对比两个时间段的指标趋势。

参数：

参数	类型	必填	说明
metric	string	是	error_rate / lag / anomaly_count / event_count
current_range	string	是	1h / 6h / 1d / 7d
compare_range	string	否	previous / last_week / last_month（默认：previous）
cluster	string	否	集群名称

输出示例：

{
  "metric": "lag",
  "current": { "range": "2026-07-04 ~ 2026-07-05", "avg": 8500, "max": 15000 },
  "compare": { "range": "2026-07-03 ~ 2026-07-04", "avg": 3200, "max": 8000 },
  "change": { "avgMultiplier": 2.66, "maxMultiplier": 1.88, "trend": "up" },
  "summary": "平均Lag比对比时段2.66倍，峰值1.88倍，趋势上升"
}

set_baseline

手动设置指标基线值，覆盖自动基线。

参数：

参数	类型	必填	说明
metric_key	string	是	如 lag:cluster:group:topic
value	number	是	基线值
metric_type	string	是	lag / error_rate / anomaly_count

list_baselines

查看所有基线，支持按指标类型过滤。

参数：

参数	类型	必填	说明
metric_type	string	否	lag / error_rate / anomaly_count

cleanup_storage

清理过期持久化数据。

参数：

参数	类型	必填	说明
retention_days	number	否	保留天数（默认：30）
dry_run	boolean	否	只预览，不实际删除（默认：false）

基线

基线定义了指标的"正常值"，用于倍数检测。

• 自动基线：基于历史数据 7 天滚动均值计算，每次分析持久化后自动更新
• 手动基线：通过 set_baseline 工具设置，覆盖同指标键的自动基线

当某指标没有基线时，倍数检测自动跳过。

数据保留

默认保留 30 天数据，超期自动清理。可配置：

配置项	环境变量	默认值	说明
storageRetentionDays	STORAGE_RETENTION_DAYS	30	保留天数
storageAutoCleanup	STORAGE_AUTO_CLEANUP	true	启用每日自动清理

手动基线永不自动删除。自动基线超过保留窗口未更新则被移除。