KanadeK/trace-aviary

# Trace Aviary [](https://github.com/KanadeK/trace-aviary/actions/workflows/ci.yml) [](LICENSE) [](https://github.com/KanadeK/trace-aviary/releases) Trace Aviary 将日志和 stack trace 聚类为“事件类别”（incident species）：即重复出现的故障系列，包含代表性样本、共同症状、时间桶以及最小重现假设。  核心价值： - 对时间戳、路径、ID 和动态值进行标准化，以防请求噪声将同一根本原因拆分。 - 使用确定性的本地 TF-IDF 聚类，无需在线模型。 - 导出事件目录，供值班工程师审查并移交给相关负责人。 ## 安装 ``` python -m pip install -e ".[dev]" ``` ## 快速开始 ``` trace-aviary sample --output examples/synthetic_logs.jsonl trace-aviary analyze examples/synthetic_logs.jsonl --clusters 5 --output dist-release/incident_catalog.json trace-aviary demo uvicorn trace_aviary.api:app --reload ``` 输入 JSONL： ``` {"timestamp":"2026-07-01T00:00:00Z","level":"ERROR","message":"checkout worker timed out acquiring inventory_lock request_id=req_12345678","stack":"File \"/srv/app/cart.py\", line 30, in inventory.lock_stock"} ``` 输出目录摘要： ``` { "total_events": 500, "clusters": [ { "sample_count": 100, "common_tokens": ["inventory_lock", "checkout", "worker"], "reproduction_hypothesis": "Reproduce by replaying an input that reaches the representative failure path..." } ] } ``` ## 功能 - 支持纯文本、JSONL 以及 Sentry 风格的 JSON 导入。 - 对路径、ID、时间戳、数字、电子邮件和常见机密信息进行标准化。 - 使用确定性 KMeans 进行 TF-IDF 聚类。 - 提供代表性堆栈选择、共同 token、时间分布以及样本计数。 - 支持 JSON 和 Markdown 事件目录导出。 - 提供 CLI、FastAPI UI、SQLite 持久化适配器、合成测试数据生成器以及静态 Pages 演示。 ## 非目标 - 不进行在线 LLM 调用。 - 不提供生产环境日志传输 agent。 - 不保证 secret 脱敏能捕捉到每一个敏感值。 ## 架构 领域核心位于 `src/trace_aviary/domain`，无需 UI 或网络访问即可进行测试。适配器负责处理文件、样本和 SQLite。CLI 和 FastAPI 调用相同的目录服务。 ## 测试 ``` python -m ruff check . python -m mypy src PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -p pytest_cov -q --cov=src --cov-report=term-missing --cov-fail-under=80 python -m build make verify make demo make package make release-check ``` 合成样本包含 500 个事件、五个已知根本原因、固定随机种子，并测试要求达到较高的 Adjusted Rand Index。 ## 隐私 Trace Aviary 是本地优先的，并在目录导出之前对常见的 token/password 形式进行脱敏处理。请勿将未脱敏的生产环境日志上传到公开 issue、Pages 或 release 资产中。 ## 竞品扫描 在 2026-07-18 进行的公开代码库抽样中，未发现同名或高度同构的活跃项目。有关扫描范围详情，请参阅 `docs/COMPETITOR_SCAN.md`。 ## 路线图 - 可配置的聚类策略和阈值扫描。 - 针对常见可观测性导出的更多导入适配器。 - 支持键盘分流操作的 HTML 目录导出。 ## 常见问题 **Trace Aviary 是否使用在线 AI 模型？** 否。 **动态请求 ID 会导致过度拆分吗？** 标准化器会在向量化之前替换常见的请求、trace、span 和 session ID。 **我可以将其用于私有日志吗？** 可以在本地使用，但在分享前请审查导出内容。

标签：API集成, Python, TF-IDF, 可观测性, 异常聚类, 文档结构分析, 无后门, 运维监控, 逆向工具