# Log Analysis > 服务端日志智能分析与日志检索最佳实践 - 解读应用日志、JSON/structured logs、HTTP/access log、数据库慢查询、消息队列、定时任务、网关/代理和系统组件日志；适配本地文件、grep/rg/zgrep/jq 输出及主流日志平台线索。按 traceId/correlationId/requestId/spanId/线程/业务 ID 拆分链路，还原请求、任务、消息或批处理时间线，诊断报错、超时、慢调用、字段为空、数据不一致、重试降级、敏感信息泄露、日志质量、索引/标签/高基数和查询范围问题。用户粘贴日志、提供日志文件路径、贴查询结果、询问“分析日志”“查日志最佳实践”“帮我看下这段 log”“接口为什么慢”“为什么失败/超时/为空”“字段在哪一跳丢了”“日志里有没有报错”“怎么搜 trace”“慢查询/消息消费/access log/任务日志排查”时使用。 - Skill: `winhok/log-analysis` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add winhok/log-analysis` - Raw SKILL.md: https://api.skillmd.com/api/skills/winhok/log-analysis/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: winhok (https://skillmd.com/u/winhok) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/winhok/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 `：围绕指定 trace/correlation id 分析。 - `--field `：进入字段溯源模式。 - `--time-window `：只分析指定时间范围。 - `--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/业务标识并核对时钟差；第一处观察到的异常不一定是最终根因。仅有 UI 现象交由 video-to-issue 提供观察；没有代码仓库、需要逆向 Web 实现证据并建立测试全局视野时使用 web-app-reverse，不能将时间相近误当同一请求。 - 结论先行：用户带问题时，报告开头直接回答。 - 证据驱动：每个判断都要能回指日志时间、字段、线程、trace 或关键片段。 - 量化表达：写“重复 17 次，总耗时约 680ms”，不要写“很多次”。 - 区分事实和推断：日志能证明的写事实，日志不足的写不确定性和下一步验证。 - 字段优先：结构化日志按字段查询和对比；文本日志才退回关键词、正则和时间邻近。 - 标准先行：用户问是否符合预期时，先列判断标准，再写事实对照和结论。 - 分支可见：链路包含分支、fallback、短路或配置开关时，写清实际走到哪个分支以及依据。 - 聚焦当前问题：其他疑点只列为次要风险，不抢主线。 - 引用敏感信息时保持最小必要；发现 token、密钥、手机号、证件号等，标注日志脱敏风险。 ## 反模式 - 不要逐行翻译日志。 - 不要按日志级别堆列表而忽略请求/任务链路。 - 不要把“日志没打印字段”断言成“服务没收到字段”。 - 不要把下游空值处理当成最早根因。 - 不要在聚焦模式里展开所有无关链路。 - 不要给出无时间窗、无关键词、无保护的大范围 grep。 - 不要为了显得完整而输出与当前问题无关的 SQL、服务调用或安全分析。 - 不要在证据不足时写“根因就是”；改写为“当前日志支持的最可能原因是”并给验证命令。 - 不要把 HTTP 200、SUCCESS 或无 ERROR 直接判定为“逻辑没问题”。 - 用户补充或修正预期后，不要沿用旧结论；必须按新预期重新判定。 ## 交付前检查 输出前逐项确认： - [ ] 选择的模式和用户意图一致。 - [ ] 用户有明确问题时，首段已经直接回答。 - [ ] 每个核心结论都有日志证据。 - [ ] “空值 / 未打印 / 查错源 / 来源不同”没有混淆。 - [ ] 用户问“是否符合预期/有没有 bug”时，已经先列出判断标准再给结论。 - [ ] 链路包含分支、fallback、短路或配置开关时，已经说明实际分支和证据。 - [ ] 深挖命令数量少而精准，并说明目的。 - [ ] 报告长度匹配日志规模：小日志短报告，大日志结构化报告。