Log analysis

log-analysis：通用服务端日志智能分析

铁律：先回答用户真正问的问题；不要把日志分析写成逐行翻译或全景流水账。

将应用日志、网关/access log、数据库慢查询、消息消费、任务调度、系统组件日志等混杂文本拆成可读链路，恢复时间线，定位异常、性能瓶颈、字段丢失和跨服务不一致，并在证据不足时给出最小深挖命令。

执行清单

复制并逐项完成：

• Step 1: 获取日志 ⚠️ REQUIRED
  • 1.1 粘贴文本：直接分析
  • 1.2 本地文件路径：读取文件或用户指定行范围
  • 1.3 远程服务器路径：要求用户粘贴内容或先导出到本地
• Step 2: 判断意图和分析模式 ⚠️ REQUIRED
  • 2.1 用户有明确问题 → 聚焦模式
  • 2.2 字段为空/丢失/不一致 → 字段溯源模式
  • 2.3 无明确问题且日志较少 → 快速概览模式
  • 2.4 无明确问题且日志较多 → 深度诊断模式
• Step 3: 识别格式并拆分链路 ⚠️ REQUIRED
  • 3.1 提取时间戳、线程/协程、级别、组件、trace/correlation id、消息体
  • 3.2 按 trace id、线程、业务 id、时间窗口逐级分组
  • 3.3 标注无法可靠归组的日志行
• Step 4: 选择查询策略（conditional）
  • 4.1 用户要“怎么查/怎么搜/最佳实践/查询太慢/为什么搜不到” → 加载 references/log-search-best-practices.md
  • 4.2 结构化日志优先按字段查询；文本日志先限定时间窗、服务、trace/业务 ID 和错误关键词
  • 4.3 避免建议把 traceId、userId、orderId、requestId 等高基数字段做索引标签
• Step 5: 分析相关链路
  • 5.1 还原请求、任务、消息或批处理生命周期
  • 5.2 检测失败、超时、重试、降级、空结果、异常堆栈和敏感信息
  • 5.3 量化耗时、频次、成功率、批量大小和异常数量
  • 5.4 用户问“是否符合预期/有没有 bug”时，先列出判断标准再判定
  • 5.5 链路包含分支、fallback、短路或配置开关时，标注实际分支路径
• Step 6: 输出报告 ⚠️ REQUIRED
  • 6.1 使用与模式匹配的报告结构
  • 6.2 结论必须引用日志证据
  • 6.3 无法确认根因时明确写出“当前日志不能证明什么”
• Step 7: 给出下一步深挖命令（conditional）
  • 7.1 只有当证据不足、日志片段截断或需要跨文件验证时才输出
  • 7.2 命令必须带目的说明，并限制范围避免全量扫盘
• Step 8: 交付前检查 ⚠️ REQUIRED
  • 8.1 没有逐行翻译
  • 8.2 没有把“未打印”写成“未收到”
  • 8.3 没有用无证据猜测代替结论
  • 8.4 用户的问题在开头被直接回答

输入处理

支持直接粘贴日志、本地日志文件路径、命令输出片段、压缩日志的 grep/zgrep 结果。若路径在远程机器上，不要假设当前环境可读；请用户粘贴片段、上传文件，或先在远端执行过滤命令。

日志极大时先让用户缩小范围：优先按 trace/correlation id、业务 id、时间窗口、错误关键词或线程名过滤。不要默认读取或要求分析超大完整日志。

分析模式

聚焦模式

触发：用户问了具体问题，例如某接口为什么慢、某任务为什么失败、某请求为什么返回空、某时间段为什么报错。

行为：先给一段直接结论，再给证据链。仍需拆分全局链路以避免漏掉根因，但只展开与问题相关的链路；其他链路只在总览中一行带过。加载 references/report-templates.md 的聚焦模板。

字段溯源模式

触发：用户关注字段为空、丢失、错值、跨系统不一致、入参和出参不一致、数据库和接口结果不一致。

行为：加载 references/field-tracing.md。沿入口、网关/中间层、服务调用、数据库/缓存、消息/事件、响应组装逐跳标注字段状态。必须区分有值、空值、未打印、名称变化、来源不同、查错数据源。

快速概览模式

触发：用户没有具体问题，且日志少于约 100 行或独立链路不超过 2 条。

行为：加载 references/report-templates.md 的快速模板。输出概览、链路总览、问题（如有）和一句话结论。正常日志不要硬凑深挖命令。

深度诊断模式

触发：用户没有具体问题，且日志较多、链路较多，或用户传入 --deep。

行为：加载 references/analysis-playbook.md 和 references/report-templates.md。覆盖链路拓扑、异常分布、性能瓶颈、数据访问、外部依赖、重试/降级、日志质量和安全风险。

日志检索/查询优化模式

触发：用户问“怎么查日志”“怎么搜 trace”“日志查询最佳实践”“为什么搜不到”“查询太慢/结果太多/漏日志”，或当前日志不足以闭环需要设计下一步查询。

行为：加载 references/log-search-best-practices.md。先明确问题、时间窗、服务范围和可用字段，再给最小查询集合。优先使用结构化字段和关联 ID；对 Loki 标签、Elasticsearch 索引字段、Cloud Logging JSON 路径等平台能力给出平台相关建议；同时提醒高基数字段应作为结构化属性/元数据或查询字段，不应盲目提升为标签。

预期行为对齐

触发：用户问“有没有 bug”“逻辑是否正确”“是否符合需求”“为什么结果不对”等需要按预期判定的问题。

行为：从用户描述中提取可验证的判断标准；若预期不完整，先列出“暂定判断标准”并标注需要确认的点。分析日志时只判断日志事实是否违反这些标准，不把 200、SUCCESS 或无 ERROR 直接等同于逻辑正确。用户补充或修正预期后，必须按新标准重新判定。

分支路径分析

触发：日志中出现多分支逻辑、配置开关、版本判断、命中/未命中、fallback、降级、重试或短路返回。

行为：提取分支入口条件，例如配置、版本、状态、开关、命中结果或错误码；标注每个关键判断的结果：命中、未命中、跳过、fallback、短路、重试或降级；记录分支后的副作用：写库、发消息、调用下游、更新缓存或返回结果；用“条件 -> 分支 -> 副作用 -> 最终结果”输出。

手动参数

• --quick：强制快速概览，除非日志不足以判断基本事实。
• --deep：强制深度诊断。
• --trace <id>：围绕指定 trace/correlation id 分析。
• --field <name>：进入字段溯源模式。
• --time-window <range>：只分析指定时间范围。
• --query-plan：只输出下一步日志检索方案和查询命令，不做完整诊断。

链路拆分优先级

1. trace id / correlation id / request id / span id：最可靠。
2. 线程名、协程名、任务名、消费者分区：适合同一执行上下文。
3. 业务 id、实体 id、消息 id、批次 id：适合跨线程或跨服务关联。
4. 时间窗口 + 语义连续性：兜底，需要标注不确定性。

同一线程可能复用处理多个请求；异步任务可能缺少 trace id；多服务日志可能格式不同。遇到这些情况时，说明归组依据和置信度。

诊断维度

按场景选择，不要机械展开所有维度：

• 失败诊断：错误级别、异常堆栈、失败计数、错误码、降级路径、最终状态。
• 性能诊断：端到端耗时、单步耗时、慢依赖、重复调用、排队/锁等待、批处理效率。
• 数据诊断：字段流转、空值来源、数据源差异、缓存与数据库不一致、写入与读取时间差。
• 依赖诊断：HTTP/RPC/消息/数据库/缓存/第三方调用的频次、耗时、状态和重试。
• 日志质量：关键字段缺失、上下文断裂、trace 丢失、敏感信息泄露、日志噪音。
• 检索质量：查询范围过宽、字段未结构化、标签/索引高基数、时间窗缺失、采样/轮转导致漏日志。

需要更细规则时加载 references/analysis-playbook.md。

深挖命令

只有在当前日志无法闭环时才输出。需要补齐具体证据命令时加载 references/grep-recipes.md；需要设计平台查询策略或解释查询质量问题时加载 references/log-search-best-practices.md。命令应优先限制 trace id、业务 id、时间窗口和文件范围；跨服务或大目录扫描必须加入 timeout、nice 或等价保护。

每条命令都必须说明“为什么查这个”。不要输出与用户问题无关的命令。

输出原则

• 结论先行：用户带问题时，报告开头直接回答。
• 证据驱动：每个判断都要能回指日志时间、字段、线程、trace 或关键片段。
• 量化表达：写“重复 17 次，总耗时约 680ms”，不要写“很多次”。
• 区分事实和推断：日志能证明的写事实，日志不足的写不确定性和下一步验证。
• 字段优先：结构化日志按字段查询和对比；文本日志才退回关键词、正则和时间邻近。
• 标准先行：用户问是否符合预期时，先列判断标准，再写事实对照和结论。
• 分支可见：链路包含分支、fallback、短路或配置开关时，写清实际走到哪个分支以及依据。
• 聚焦当前问题：其他疑点只列为次要风险，不抢主线。
• 引用敏感信息时保持最小必要；发现 token、密钥、手机号、证件号等，标注日志脱敏风险。

反模式

• 不要逐行翻译日志。
• 不要按日志级别堆列表而忽略请求/任务链路。
• 不要把“日志没打印字段”断言成“服务没收到字段”。
• 不要把下游空值处理当成最早根因。
• 不要在聚焦模式里展开所有无关链路。
• 不要给出无时间窗、无关键词、无保护的大范围 grep。
• 不要为了显得完整而输出与当前问题无关的 SQL、服务调用或安全分析。
• 不要在证据不足时写“根因就是”；改写为“当前日志支持的最可能原因是”并给验证命令。
• 不要把 HTTP 200、SUCCESS 或无 ERROR 直接判定为“逻辑没问题”。
• 用户补充或修正预期后，不要沿用旧结论；必须按新预期重新判定。

交付前检查

输出前逐项确认：

• 选择的模式和用户意图一致。
• 用户有明确问题时，首段已经直接回答。
• 每个核心结论都有日志证据。
• “空值 / 未打印 / 查错源 / 来源不同”没有混淆。
• 用户问“是否符合预期/有没有 bug”时，已经先列出判断标准再给结论。
• 链路包含分支、fallback、短路或配置开关时，已经说明实际分支和证据。
• 深挖命令数量少而精准，并说明目的。
• 报告长度匹配日志规模：小日志短报告，大日志结构化报告。