log-analysis

日志分析

何时使用此技能

• 主要任务是只读日志分诊，而不是修改代码或设计监控。
• 用户想要的是第一个可执行的阻塞问题，而不是逐行复述。
• 证据来自应用、API、工作进程、代理、容器、Pod、浏览器、CI 或 JSON 日志。
• 隔离出首次故障后，用户还需要总结重复出现的特征或影响范围。
• 实际问题是**“哪些行重要／真正的错误是什么／级联故障从哪里开始？”**，即使用户没有使用“分诊”一词。

以下情况请勿将此技能作为主要工作流：

• 日志是 Unity / Unreal 构建、烘焙、打包、编辑器或播放器日志 → 使用 game-build-log-triage。
• 实际任务是插桩、仪表板、告警、采集、保留或可观测性覆盖 → 使用 monitoring-observability。
• 可能的阻塞问题已知，用户现在需要的是复现、假设或修复方案 → 使用 debugging。
• 主要任务是跨日志或遥测类别反复查找异常／规则，而不是对首次故障进行分诊 → 使用 pattern-detection。

核心思路

log-analysis 应该像数据包路由器，而不是一部庞大的故障排查百科全书。

1. 将请求规范化为一个主要日志数据包。
2. 在解读之前缩小证据范围。
3. 隔离出最早出现的可执行故障。
4. 将重复出现的后续问题归纳为模式／影响范围说明。
5. 一旦任务转为调试、可观测性设计、异常排查或引擎专项分诊，就立即转交。

选择数据包前，请先阅读以下支持文档：

• references/intake-packets-and-route-outs.md
• references/triage-playbook.md
• references/source-boundaries.md

说明

步骤 1：规范化请求

先将提示整理为以下信息形态：

log_analysis_packet:
  primary_packet: app-runtime | container-runtime | browser-plus-api | ci-cascade | structured-json | security-signal
  source_shape: app | proxy | worker | browser | ci | container | pod | json | mixed | unknown
  environment: local | ci | staging | production | browser | container | pod | unknown
  failure_goal: first-blocker | cascade-start | repeated-signature | blast-radius | suspicious-access | unknown
  anchor: timestamp | request-id | trace-id | job-build-id | browser-route | none | unknown
  route_after: stay-here | debugging | monitoring-observability | pattern-detection | game-build-log-triage

本次运行请选择一个主要数据包。如果两个都看起来合适，请选择能以更低成本最快减少不确定性的数据包。

步骤 2：选择数据包

数据包	适用场景	最适合处理	典型锚点
app-runtime	关键证据来自应用/API/工作进程/代理文本日志	崩溃、堆栈跟踪、请求失败、队列毒消息	最早出现的致命/错误行、路由、服务、请求 ID
container-runtime	证据来自 docker logs、kubectl logs、Pod 输出或部署时段内的重启	容器崩溃、环境变量/配置不匹配、依赖连接问题、重启循环	Pod/容器名称、部署时段、主机、请求 ID
browser-plus-api	浏览器控制台/网络症状需要服务端确认	401/403/500 流程、请求失败、CORS/身份验证不匹配、SSR/客户端分歧	路由、请求 ID、时间戳、浏览器/网络跟踪
ci-cascade	CI 输出在一个阻断问题后包含许多次级故障	安装/导入/测试/构建级联、缺少依赖/配置、运行器不匹配	作业名称、步骤名称、阶段、最早的堆栈跟踪/导入错误
structured-json	日志为 JSON 或包含丰富字段的事件记录	错误类型分组、请求/跟踪关联、工作进程/事件排查	级别、服务、请求 ID、跟踪 ID、租户、事件名称
security-signal	访问/错误日志显示可疑探测或身份验证/权限异常	重复的 401/403/404 探测、令牌滥用、速率限制风暴	IP/用户/会话、路由系列、状态码、时间范围

数据包规则：

• 对于纯文本堆栈跟踪和服务端日志，优先使用 app-runtime。
• 当重启时间、Pod 身份或环境变量/部署上下文很重要时，优先使用 container-runtime。
• 当仅凭前端症状不足以判断时，优先使用 browser-plus-api。
• 当可见故障可能只是泛化的中止噪声时，优先使用 ci-cascade。
• 当利用字段分组和关联比扫描自由文本更高效时，优先使用 structured-json。
• 仅当可疑访问/身份验证行为是主要排查目标时，才使用 security-signal；否则，将看似安全相关的噪声保留在包含首个阻断问题的数据包中。

步骤 3：在阅读所有日志之前先缩小范围

解读日志前，至少采取一种缩小范围的方法：

• 限定时间范围
• 按请求/跟踪/作业/构建/会话/租户标识符筛选
• 将致命/可操作行与重试及后续连带问题分开
• 将一个嘈杂来源与多个受影响来源分开
• 将浏览器症状行与服务端阻断问题行分开
• 在 CI 中，先找到最早失败的步骤，再总结完整输出记录

各数据包的实用启发：

• app-runtime → 优先查找异常/致命/失败/超时/拒绝
• container-runtime → 优先查找重启时段以及依赖/连接/环境不匹配
• browser-plus-api → 先查看后端身份验证/配置/运行时证据，再看泛化的客户端症状
• ci-cascade → 先查看最早的导入/配置/构建/测试故障，再看中止/结尾行
• structured-json → 先按消息类型、异常类、请求 ID 或服务分组，再阅读原始行
• security-signal → 在升级处理前，区分大范围探测与单个客户端故障

步骤 4：隔离首个可操作故障

按以下顺序处理：

1. 硬性中断 — 崩溃、panic、未捕获异常、进程退出、构建失败
2. 依赖/环境阻断问题 — 缺少配置、密钥、DNS、文件、服务、身份验证或连接
3. 请求/运行时故障 — 500、超时、被拒绝的 Promise、队列毒消息、解析器故障
4. 连带问题 — 重试、次要警告、重复的健康检查失败、泛化的中止文本

不要将 20 行重复的下游日志报告为 20 个不同原因。

步骤 5：关联并分类

如果证据来自多个来源，请进行关联，而不是简单拼接。

主要分类类别：

• missing-config-or-secret
• dependency-or-connection
• auth-or-permission
• request-or-runtime-error
• data-shape-or-validation
• resource-or-capacity
• browser-network-mismatch
• ci-build-test-failure
• security-or-suspicious-pattern
• unknown-needs-more-context

优先使用的关联锚点：

• 时间戳范围
• 请求 / 跟踪 / 关联 ID
• 作业 / 构建 ID 或 CI 步骤
• 服务 / 工作进程 / pod / 容器名称
• 路由、浏览器操作或 API 端点
• 在安全的情况下，用户 / 租户 / 会话标识符

步骤 6：返回分诊简报

默认响应格式：

# Log Triage

## Source
- Packet: app-runtime | container-runtime | browser-plus-api | ci-cascade | structured-json | security-signal
- Environment: local | CI | staging | production | browser | container | pod
- Confidence: high | medium | low

## First actionable failure
- Line or excerpt: `...`
- Why it matters: ...
- Why later lines look secondary: ...

## Pattern / blast radius
- Repeated signature: ...
- Scope: one request | repeated requests | one worker | one deploy window | one environment | broad

## Classification
- Primary bucket: ...
- Secondary bucket: ...

## Likely root cause
- 1-3 sentence explanation grounded in the evidence

## Next read-only checks
1. ...
2. ...
3. ...

## Route-out
- stay in `log-analysis` | `debugging` | `monitoring-observability` | `pattern-detection` | `game-build-log-triage`

步骤 7：尽快转交

当接下来的工作不再是首次故障日志分诊时，请切换方向：

• 复现、假设、代码 / 配置修复 → debugging
• 仪表板、告警、摄取、遥测覆盖范围、保留期限 → monitoring-observability
• 跨多个时间窗口或数据集反复搜索特征 → pattern-detection
• Unity / Unreal 构建 / 编辑器 / 打包日志 → game-build-log-triage

如果摘录太短或从故障链中途开始：

1. 将置信度标为低
2. 请求提供最早的错误簇，或首个阻塞点附近的 20-80 行内容
3. 仅在必要时请求一个锚点：时间范围、请求 ID、作业 / 构建、pod / 容器或浏览器路由
4. 不要对截断的摘录妄下定论

示例

示例 1：容器依赖故障

提示词：

kubectl logs 显示 Error: connect ECONNREFUSED redis:6379，随后出现几十行 job retry failed。

良好的响应格式：

• 选择 container-runtime
• 将 Redis 连接失败识别为首个可采取行动的阻塞点
• 将后续重试行归为连带结果
• 只有在隔离出阻塞点后，才转交给 debugging 或 monitoring-observability

示例 2：浏览器与 API 不匹配

提示词：

浏览器控制台显示 Failed to fetch，网络面板显示 /api/session 返回 401，服务器日志显示 JWT audience invalid。

良好的响应格式：

• 选择 browser-plus-api
• 将后端身份验证校验识别为可采取行动的阻塞点
• 将浏览器故障视为症状，而非原因
• 明确配置 / 代码方面的可疑点后，再转交给 debugging

示例 3：CI 故障链

提示词：

CI 最后显示 test suite aborted，但更早之前出现了 ModuleNotFoundError: No module named 'dotenv'。

良好的响应格式：

• 选择 ci-cascade
• 隔离出最早的导入失败
• 将中止 / 页脚文本视为连带结果
• 确认失败的依赖路径后，再转交给 debugging

示例 4：自动化 / webhook JSON 日志

提示词：

这些 JSON webhook 日志显示，在一次 invalid API key 响应后反复出现 status=429 重试。真正需要关注的是什么？

良好的响应格式：

• 根据主要任务是调查身份验证滥用，还是单个错误凭据，选择 structured-json 或 security-signal
• 隔离出首次凭据 / 身份验证失败
• 单独汇总重试量
• 只有用户希望开展更广泛的异常排查时，才将重复特征搜索转交给 pattern-detection

最佳实践

1. 选择能够回答问题的最小数据包。
2. 首先指出最早的阻塞点，而非最显眼的日志行。
3. 将重复的连带结果归为一个特征或影响范围摘要。
4. 关联浏览器 / 网络 / 应用证据，而不是分别总结各个来源。
5. 在此技能中，所有建议的检查都应为只读操作。
6. 将引擎专用日志视为严格的专业领域边界。
7. 一旦工作转为调试、可观测性设计或异常排查，就立即转交。

参考资料

• references/intake-packets-and-route-outs.md
• references/triage-playbook.md
• references/source-boundaries.md