German4341374/distributed-log-intelligence

# 分布式日志智能分析 [](https://github.com/German4341374/distributed-log-intelligence/actions/workflows/ci.yml) [](https://www.python.org/) [](LICENSE) `distributed-log-intelligence` 是一款本地优先的命令行工具，专为需要在不上传机密数据的情况下调查多个服务日志的支持与运维工程师而设计。它支持流式读取纯文本、JSON Lines、CSV 和 gzip 文件，将时间戳统一转换为 UTC，对重复出现的故障进行分组，发现突发流量和异常时间窗口，并通过 correlation ID 重建跨服务调用流。 ## 核心亮点 - 以流式方式读取单个或多个文件，而非将完整数据集载入内存。 - 自动检测纯文本、JSONL 和 CSV 格式；透明读取 gzip 输入。 - 识别常见的时间戳字段，并将带有时区或无时区的时间戳标准化为 UTC。 - 将 DEBUG、INFO、WARNING、ERROR 和 CRITICAL 等日志级别进行标准化。 - 在替换易变的 UUID、IP 地址、时间戳、ID 和数字之后，对错误消息进行分组。 - 利用基于磁盘的追踪索引，持续监测 correlation ID 并构建有序的服务调用链。 - 在可配置的时间窗口内，查找基于阈值的错误爆发和 z-score 异常。 - 对比基准期与当前期的数据，以发现新增的、已解决的以及呈增长趋势的错误。 - 对电子邮件、IPv4 地址、电话号码、bearer token、API key 和机密信息进行脱敏掩码处理。 - 导出 JSON、Markdown、自包含的 HTML 以及 JUnit XML 报告。 - 明确处理格式错误的记录，并返回对自动化友好的退出代码。 ## 架构 ``` flowchart LR A["Plain / JSONL / CSV / gzip files"] --> B["Small-sample format detector"] B --> C["Streaming record parser"] C --> D["Pydantic LogEvent validation"] D --> E["UTC normalization"] E --> F["Bounded-memory analyzer"] F --> G["Error grouping"] F --> H["Window statistics and anomalies"] F --> I["Correlation tracking"] I --> J["Disk-backed ordered trace"] G --> K["Console / JSON / Markdown / HTML / JUnit"] H --> K J --> K C --> L["Malformed record samples"] L --> K ``` 解析器采用迭代器模式。分析过程中的内存占用会随着保留的不同分组、服务、correlation ID 和时间窗口数量增加而增长——而非取决于输入的记录总数。追踪排序使用了一个临时的 SQLite 数据库，因此无需在 RAM 中对大规模的关联流进行排序。有关详细的内存模型与权衡，请参阅 [architecture.md](docs/architecture.md)。 ## 环境要求 - Python 3.12 或更高版本（容器中使用的是 3.14） - [`uv`](https://docs.astral.sh/uv/)，用于执行文档中所述的开发工作流 - 可选使用 Docker，用于运行隔离的 CLI 镜像 - 可选使用 GNU Make；每个 Make 目标均映射至文档记录的 `uv` 命令 该项目完全在本地运行，可以通过 WSL2 在 Linux 或 Windows 上执行。 ## 快速开始 ``` git clone https://github.com/German4341374/distributed-log-intelligence.git cd distributed-log-intelligence uv sync --locked --extra dev uv run distributed-log-intelligence generate-demo demo.jsonl --lines 10000 uv run distributed-log-intelligence analyze demo.jsonl --output report.html ``` 生成并分析 gzip 数据： ``` uv run dli generate-demo demo.csv --format csv --lines 50000 --gzip uv run dli analyze demo.csv.gz --window-minutes 5 --top 15 --output report.json ``` ## 命令说明 ### 分析多个文件 ``` uv run dli analyze gateway.log orders.jsonl payments.csv.gz \ --default-timezone Europe/Berlin \ --window-minutes 10 \ --burst-threshold 20 \ --output incident-report.md ``` 当 CI 任务需要在遇到特定情况（如异常）时判定为失败，可使用 `--fail-on-malformed` 或 `--fail-on-anomaly`。 ### 对比不同时间段 基准期文件以位置参数提供。对每一个当前期的文件重复使用 `--current` 参数： ``` uv run dli compare logs/baseline-1.jsonl logs/baseline-2.jsonl \ --current logs/current-1.jsonl \ --current logs/current-2.jsonl \ --output comparison.html ``` ### 跨服务追踪请求 ``` uv run dli trace demo-00000042 gateway.log orders.jsonl payments.csv.gz \ --max-events 2000 \ --output trace.json ``` 追踪功能会精确匹配 correlation ID。结果中的消息在输出前会进行脱敏掩码处理。 ### 对文件进行脱敏 ``` uv run dli redact production.log production.redacted.log uv run dli redact archive.jsonl.gz archive.redacted.jsonl.gz ``` 源文件永远不会被修改。若要覆盖已存在的目标文件，需添加 `--overwrite` 参数。 ### 验证输入 ``` uv run dli validate gateway.log api.jsonl data.csv.gz --output validation.xml echo $? # 0 for fully valid input, 1 when malformed records exist ``` ### 生成确定性演示日志 ``` uv run dli generate-demo demo.log --format plain --lines 1000 --seed 42 uv run dli generate-demo demo.jsonl --format jsonl --lines 1000 uv run dli generate-demo demo.csv --format csv --lines 1000 --gzip ``` 所有演示用的身份信息、地址和事件均为合成的虚拟数据。 ## 支持的输入格式 JSONL 和 CSV 格式支持识别以下字段的别名： | 标准字段名 | 可识别的示例 | |---|---| | timestamp | `timestamp`, `@timestamp`, `time`, `datetime`, `date` | | level | `level`, `severity`, `loglevel`, `log_level` | | service | `service`, `app`, `application`, `component`, `logger` | | message | `message`, `msg`, `event`, `text` | | correlation ID | `correlation_id`, `trace_id`, `request_id` 及其紧凑/连字符形式 | 纯文本输入采用以下结构： ``` 2026-01-15T08:00:00Z ERROR service=payments correlation_id=req-0042 database timeout after 5000 ms ``` 无时区信息的时间戳会根据 `--default-timezone` 进行解释，随后转换为 UTC。JSONL 和 CSV 格式支持接受以秒或毫秒为单位的数字 Unix 时间戳。 ## 报告与退出代码 输出的文件扩展名决定了格式：JSON (`.json`)、Markdown (`.md`)、HTML (`.html`) 或 JUnit XML (`.xml`)。当指定了 `--output` 时，可以使用 `--report-format` 覆盖默认格式。 | 退出代码 | 含义 | |---:|---| | 0 | 命令执行完毕，且配置的质量检测门禁均已通过 | | 1 | 验证过程中发现格式错误的数据、追踪未找到匹配项，或启用的分析门禁检测失败 | | 2 | 使用方式、输入数据、时间戳、文件系统或配置错误 | ## 开发指南 ``` make setup make lint make test make build make demo make benchmark ``` 不使用 Make 的等效命令： ``` uv sync --locked --extra dev uv run ruff format --check . uv run ruff check . uv run mypy src benchmarks uv run pytest uv build ``` ## Docker ``` docker build --target runtime -t distributed-log-intelligence:0.1.0 . docker run --rm distributed-log-intelligence:0.1.0 --version docker run --rm -v "$PWD/logs:/data:ro" \ distributed-log-intelligence:0.1.0 \ analyze /data/app.jsonl ``` 运行时镜像采用多阶段构建，不包含任何编译器工具链，并以 UID 10001 身份运行。请以只读方式挂载生产日志。该镜像不会发起任何网络请求。 ## 检测细节与局限性 - 错误爆发检测是对每个观察到的窗口执行的绝对阈值检查。 - 统计异常检测使用总体 z-score，且要求至少观察到六个有效窗口。 - 系统不会自动填补空的时间窗口。非平稳、季节性、稀疏或多模态的日志可能会导致 z-score 产生误导；这仅作为一种分诊信号，而非最终的事故定性结论。 - 消息分组是确定性但基于启发式算法的。过于激进的数字替换可能会将那些唯一有意义区别仅为一个数字的错误合并在一起。 - 格式检测最多只读取前五个非空行；基于文件扩展名的检测具有最高优先级。 - 在文本解码过程中，无效的 UTF-8 字节会被替换，受影响的行可能仍会被解析。 - 脱敏组件采用尽力而为的模式匹配，并非防数据泄露的绝对保障。 - correlation 追踪是精确匹配，当 ID 缺失或被重用时，系统不会进行因果关系的推断。 在将该工具用于机密日志之前，请参阅 [data-handling.md](docs/data-handling.md) 了解对格式错误记录的处理机制，并查阅 [privacy.md](docs/privacy.md)。 ## 性能基准测试 基准测试生成器会创建确定性的临时 JSONL 文件，运行与 CLI 相同的流式分析器，并记录运行耗时、吞吐量以及 Python 的峰值内存分配。 ``` uv run python benchmarks/run_benchmark.py --sizes 10000 50000 200000 --repeats 3 ``` [benchmark-results.md](docs/benchmark-results.md) 中提交的结果，均是在运行该确切代码版本后记录的。测试结果因运行环境而异，不作为任何性能承诺。 ## 安全说明 - 处理过程完全在本地进行；应用程序不包含任何遥测、数据分析、HTTP 客户端或数据上传途径。 - 输出的示例及格式错误行的预览均已进行脱敏掩码处理。 - 原始输入依然属于敏感数据。请根据同等的数据安全分类标准，妥善保护源文件、报告文件、临时目录、Shell 历史记录以及 CI 构建产物。 - 即便在进行了 PII（个人身份信息）脱敏之后，报告中仍可能包含具有业务敏感性的服务名称和消息结构。 - 运行容器时可切断网络访问以实现更高级别的隔离：`--network none`。 安全报告将按照 [SECURITY.md](SECURITY.md) 中的说明进行处理。 ## 项目结构 ``` src/distributed_log_intelligence/ CLI, parsing, analysis, privacy, and reports tests/ Unit, integration, CLI, and fixture tests benchmarks/ Deterministic streaming benchmark docs/ Architecture, privacy, data handling, results .github/workflows/ Quality, test, benchmark, build, and container CI ``` ## 未来改进计划 - 针对基数极高的时间范围，提供可选的基于磁盘的聚合方案。 - 提供可插拔的解析器，以支持特定厂商的专有格式，而无需扩充核心 schema。 - 引入稳健的中位数 / MAD（绝对中位差）算法和季节性基线，以优化异常检测。 - 提供可选的 IPv6 及特定组织专属标识符的脱敏掩码配置。 - 引入蓄水池抽样算法，以获取具有代表性的错误示例。 ## 许可协议 基于 [MIT 许可证](LICENSE) 开源发布。

标签：API集成, Python, 可观测性, 异常检测, 数据脱敏, 无后门, 请求拦截, 逆向工具