infrahub-analyzing-diagnostics

Infrahub 诊断分析器

概述

infrahub-collecting-diagnostics 会生成一个捆绑包； 此技能是下一步——它会读取该捆绑包， 并将原始日志转换为分诊报告。它会解析 bundle_information.json，扫描每个服务的 日志以查找错误信号（回溯、ERROR/CRITICAL 行、panic、OOM 杀死、重启证据）， 将相关错误关联为事件，并搜索现有的 opsmill/infrahub GitHub 问题， 让用户在提交任何问题前了解其崩溃是否 已为人所知。

输出是一份基于捆绑包证据的发现报告——而非修复方案。此技能对部署严格只读：它会读取 已收集捆绑包中的文件并运行 GitHub 搜索；绝不会触及正在运行的 Infrahub 实例，也不会应用任何修复措施。

何时使用

当用户表达以下意图时，触发此技能：

• “我收集了一个捆绑包——能告诉我出了 什么问题吗？”
• “分析这些 Infrahub 日志／这个捆绑包”
• “捆绑包中的回溯是什么意思？”
• “这是一个已知的 Infrahub 问题吗？”
• “为什么 task-worker 一直在重启？”

以下情况不要触发：

• 还没有捆绑包——先转交给 infrahub-collecting-diagnostics 进行收集。不要在此处自行收集日志。
• 用户想要提交错误报告或功能请求 （使用 infrahub-reporting-issues）
• 用户在询问实时数据的运维问题（使用 infrahub-analyzing-data）

工作流

按顺序执行以下步骤。

1. 询问捆绑包的位置（用户确认）

询问用户捆绑包的位置——绝不要扫描 文件系统来查找，也不要假定使用了收集器的默认 输出目录。一台机器上通常会有多个 捆绑包，选错会导致报告对错误事件作出 看似确定的结论。 可以提示默认位置 （未设置 --output-dir 时为 ./infrahub_bundles/），但路径必须由用户提供。只有当用户已经给出路径或粘贴了 捆绑包内容时，才跳过此问题。用户提供路径后，确认其看起来像是 infrahub-collect 捆绑包——其中有一个包含 bundle_information.json 的 bundle/ 目录。 如果完全没有捆绑包，请停止并转交给 infrahub-collecting-diagnostics；不要用 docker compose logs／kubectl logs 代替。 请参阅 rules/workflow-ask-bundle-location.md。

2. 先读取清单，再确定部署上下文

打开任何日志之前，先读取 bundle/bundle_information.json。它记录了收集的内容、失败项以及对应的部署。收集失败本身 就是发现——无法收集日志的服务往往正是 宕机的服务。请参阅 rules/workflow-manifest-first.md。

然后确认部署上下文——正在运行的 Infrahub 版本、拓扑结构（Compose 或 Kubernetes）、副本数——并以此作为报告的开篇。版本信息决定了之后如何将匹配到的 GitHub 问题 转化为结论（“已在 X.Y.Z 中修复—— 请升级”或“已在运行修复版本——可能是 回归问题”）。请参阅 rules/workflow-deployment-context.md。

3. 扫描错误信号

扫描 bundle/logs/ 下的所有服务目录，而不只是服务器目录，查找 rules/triage-error-signals.md 中列出的信号类别：Python 回溯、ERROR/CRITICAL 日志行、panic、 OOM 杀死进程以及连接失败。将任何 *.previous.log 文件视为重启证据，并读取其末尾内容——重启前的日志通常会包含 崩溃原因 （rules/triage-restart-evidence.md）。 reference.md 中按信号类别提供了可直接使用的 grep 模式。

如果清单显示已收集基准测试（create --benchmark），请结合日志评估基准测试结果——单 CPU 得分以及 Neo4j/PostgreSQL 卷的存储 IOPS，往往能决定性能缓慢的症状究竟是软件问题还是主机规格不足。如果未收集基准测试，且症状表现为性能问题，报告必须建议下次创建 bundle 时使用 --benchmark。参见 rules/triage-benchmark-results.md。

4. 将信号关联为事件

按时间戳和因果链将原始信号归类为事件——每个根本问题对应一个事件，并区分根因错误与下游服务中的级联错误。14:02 时数据库发生 OOM，随后服务器在 14:02 之后出现连接错误，这属于同一个事件，而不是两个。参见 rules/correlate-into-incidents.md。

5. 与现有 GitHub issue 匹配

对于有回溯或独特错误消息支撑的每个事件，根据稳定部分构建搜索键（异常类、规范化消息、最内层的 Infrahub 堆栈帧——去除可变 ID、分支名称和主机名），然后搜索：

gh search issues --repo opsmill/infrahub "<stable keywords>"

默认搜索会涵盖打开和关闭的 issue——不要传入 --state，否则会漏掉其中一部分。

列出最匹配的结果及其标题、状态和 URL——这就是 gh search issues 返回的全部信息。该输出不包含修复版本，因此请打开可能匹配的 issue 查看修复版本，并将其与步骤 2 中的部署环境进行比较；如果 issue 未注明版本，请如实说明，并保留升级问题待定。关于搜索键的构建方式以及 gh 不可用时的替代方法，请参见 rules/match-stable-search-keys.md； 关于读取匹配结果的命令，以及搜索前值得检查的已知故障模式，请参见 reference.md——若干常见症状已有明确原因，利用这些原因可以进行有针对性的搜索，而不是泛泛搜索。

6. 报告调查结果

撰写调查结果报告：每个事件单独设一节，列出严重程度、证据（bundle 文件路径及引用的摘录）、关联推理，以及匹配的 GitHub issue。每项结论都必须能追溯到引用的 bundle 行；未知信息应明确标为未知 （rules/report-evidence-per-finding.md）。 在待解决问题中说明该症状能否按需复现，以及最近一次复现的时间——明确的复现时间戳有助于缩小事件时间范围，并告知下一个 bundle 应收集哪些信息。 报告可以建议后续步骤，但不得实际执行——不得重启或修改配置 （rules/scope-read-only-analysis.md）。

7. 移交

根据调查结果选择合适的移交方式，并以此收尾：

• 找到匹配的已打开 GitHub issue → 将用户引导至该 issue；如需评论并提交复现信息，应通过 infrahub-reporting-issues。
• 未找到匹配项且用户希望提交 issue → 移交给 infrahub-reporting-issues。切勿通过此技能运行 gh issue create。
• 需要更深入的专家帮助 → 将 bundle 和本报告提交给 OpsMill 支持团队，并遵循 infrahub-collecting-diagnostics 中的分享前审核流程。如果调查结果表明需要复现器，先提出一个最小可复现示例；完整备份（--include-backup）是最后手段，不应作为默认要求。

参见 rules/cross-link-skill-boundaries.md。

规则类别

前缀	类别	描述
workflow	工作流	先检查清单；收集失败属于发现项
triage	分类排查	错误信号类别、所有服务、重启证据
correlate	关联分析	将信号归并为事件；区分根因与级联影响
match	问题匹配	针对 opsmill/infrahub 问题的稳定搜索关键词
report	报告	每项发现都要有证据；未知项仍标记为未知
scope	范围	仅限分析——不做变更，不做修复
cross-link	交叉链接	移交给相关技能

完整索引请参阅 rules/_sections.md。

支持性参考资料

• reference.md — 信号类别的 grep 模式、各服务的日志格式、清单字段以及 gh search 用法。 在第 3 至第 5 步阅读。
• examples.md — 端到端示例： 输入捆绑包摘录，输出发现项报告。
• ../infrahub-collecting-diagnostics/reference.md — infrahub-collect 生成的权威捆绑包布局。
• ../infrahub-common/rules/workflow-information-priority.md -- 优先使用技能内容；确实存在信息缺口时，了解如何查阅 docs.infrahub.app。

反模式

• 推测捆绑包的位置。 不扫描文件系统， 不采用“最新目录优先”，也不假设位置是 ./infrahub_bundles/。应询问用户，由用户指定路径。
• 没有证据就诊断。 每项发现都要引用捆绑包路径和摘录原文。 没有日志行支持的合理推测仍属猜测， 必须明确标注。
• 只报告一串错误。 单次数据库 OOM 引发的下游 50 个连接错误 只算一个事件。报告前先进行关联分析。
• 使用易变关键词搜索 GitHub。 分支名称、 UUID、主机名和时间戳会导致搜索无结果。剔除这些内容， 搜索稳定部分。
• 修复而非分析。 不重启服务，不执行 docker/kubectl 变更，不编辑配置。 建议写入报告；操作交由用户或 OpsMill 支持团队处理。
• 通过此技能提交 GitHub 问题。 这属于 infrahub-reporting-issues。应交叉链接，而非重复其路由和脱敏流程。
• 捆绑包不完整时手动重新收集。 部分捆绑包在部署降级时是预期情况；清单会记录缺失项。 如果确实需要更多数据，应移交给 infrahub-collecting-diagnostics。