log-analyzer

日志分析器

概述

日志查看器会筛选行。本技能会查找模式。

当 Agent 运行时、工具进程、网关、调度器或其他服务产生了大量日志，单独的 grep 匹配结果已不足以解释系统行为时，可使用此技能。分析器会解析标准日志行，对重复消息进行规范化，按组件和工具对错误分组，并生成结构化异常报告，适用于调试会话或 cron 摘要。

该脚本有意保持轻量且可移植：它仅使用 Python 标准库，可处理任何包含时间戳、级别、可选组件和消息字段的文本日志。对于非结构化日志，它也提供尽力而为的回退处理。

快速开始

cd agent-ops/log-analyzer
python scripts/analyze_logs.py scan --log-file agent.log --since 24h

要从 Hermes 配置文件的会话 DB 获取每个工具的失败率（基于结构化的 exit_code 信号，而非对内容使用正则表达式）：

python scripts/state_failures.py                 # last 7 days, dashboard
python scripts/state_failures.py --days 30 --json
python scripts/state_failures.py --quiet         # cron: silent when healthy

参见 references/state-failure-monitor.md，了解来源信息（改编自 hermes-dojo 的概念）、说明结构化信号为何重要的峰值证据，以及解读说明。

要写入 JSON，以供后续渲染为 Markdown：

python scripts/analyze_logs.py scan --log-file agent.log --since 24h --output scan.json
python scripts/analyze_logs.py report --scan scan.json --output report.md

要进行兼容 cron 的异常检测：

python scripts/analyze_logs.py scan --log-file agent.log --since 24h --quiet

如果未发现异常，--quiet 会以 0 退出且不打印任何内容。如果存在异常，它会输出 JSON 报告，以便调度器发送摘要。

检测内容

1. 错误集群 — 在所选时间范围内重复 3 次或以上的相同规范化错误消息。分组前会将 URL、IP 地址和数字替换为占位符，因此即使重复失败的 ID 不同，也能归入同一集群。
2. 限流命中 — HTTP 429、rate limit、rate_limit、too many requests 和 quota exceeded 模式。如果能检测到提供方名称，分析器会按提供方对这些结果分组。
3. 超时模式 — timeout、timed out、deadline exceeded 和 connection timeout。结果按检测到的工具名称分组，并包含日志中出现的示例 URL。
4. 工具失败 — 按从 tool: terminal、tool_call: web_search、tool terminal failed 等模式中提取的工具名称，或由 tools 组件输出的错误行分组。
5. 会话崩溃 — 致命错误、未处理的异常、堆栈跟踪、Traceback、Exception 和 segfault 标记。多行堆栈跟踪会与附近的上下文一起归为一条崩溃记录。
6. 组件细分 — 按组件统计错误和警告数量，例如 gateway、agent、tools、cron 或 unknown。
7. 错误时间线 — 按小时分桶统计错误数量，以发现部署或计划任务后的峰值和回归。

检测标准和解读说明请参见 references/anomaly-types.md。

日志格式支持

解析器可处理以下格式的标准日志行：

2026-07-06 12:30:45 ERROR [gateway] Connection refused
2026-07-06T12:30:45Z ERROR gateway: Connection refused
12:30:45 ERROR Connection refused

它可识别 ERROR、WARN、WARNING、INFO、DEBUG、FATAL 和 CRITICAL 级别。组件可以出现在级别后的方括号中，也可以作为级别后的 component:。仅包含时间的行会以当天为基准（作为库调用时，则以提供的默认日期为基准）。对于非结构化行，解析器会逐行尽力扫描，因此即使无法解析时间戳，明显的 ERROR/WARN 字符串仍会被计数。

示例和添加自定义模式的指南请参见 references/log-formats.md。

CLI 命令

scan — 分析日志文件中的模式

python scripts/analyze_logs.py scan --log-file LOGFILE [--since TIME] [--output report.json] [--quiet]

选项：

• --log-file LOGFILE — 必填的日志文件路径。
• --since TIME — 可选的时间范围：分钟/小时/天/周，例如 30m、1h、24h、7d、2w；默认包含所有行。
• --output report.json — 将 JSON 写入文件，而不是标准输出。
• --quiet — cron 模式：未发现异常时不输出内容。

report — 根据扫描 JSON 渲染 Markdown

python scripts/analyze_logs.py report --scan scan.json [--output report.md]

报告包含概览计数、每种异常类型各自的一个分节、组件细分表格，以及按小时统计的错误时间线。

tail — 最近行智能 tail

python scripts/analyze_logs.py tail --log-file LOGFILE [--lines N] [--since TIME]

智能 tail 会输出纯文本，并带有适合在聊天中发送的标记：

• 普通行：无标记
• 警告：⚠️
• 错误：❌
• 重复出现的近期错误：当同一规范化错误出现 3 次或以上时，标记为 🔥

输出格式

scan 会输出包含以下顶层字段的 JSON：

• log_file、lines_analyzed、time_window
• anomalies.error_clusters、anomalies.rate_limits、anomalies.timeouts、 anomalies.tool_failures、anomalies.crashes
• component_breakdown
• error_timeline
• total_errors、total_warnings、has_anomalies

report 会将该 JSON 转换为 Markdown：

# Log Analysis Report

## Overview
- Log file: agent.log
- Lines analyzed: 1542
- Time window: 24h
- Total errors: 12 | warnings: 20
- Anomalies detected: 5 types

定时摘要集成

对于定时摘要，请以静默模式运行 scan，仅在输出非空时将其包含在内：

python scripts/analyze_logs.py scan --log-file /var/log/agent.log --since 24h --quiet --output /tmp/log-scan.json
if [ -s /tmp/log-scan.json ]; then
  python scripts/analyze_logs.py report --scan /tmp/log-scan.json
fi

scheduled-summary 作业可以将 Markdown 输出添加到“Log anomalies”标题下。请让分析时间窗口与摘要时间窗口保持一致（例如，每日摘要使用 24 小时），以免计数重叠或遗漏。

对于 state.db 故障率摘要（考虑到会话数量，每周一次是合理的频率）：

python scripts/state_failures.py --quiet --days 7

如果时间窗口内没有故障，该命令不会输出任何内容（退出码为 0），因此可将其用作 no_agent cron 作业，仅在出现问题时发送通知。有关类别含义，请参阅 references/state-failure-monitor.md（在实际数据中，超时最值得采取行动）。

常见陷阱

1. 日志轮转会破坏时间窗口。 如果昨天的文件已被轮转移出，仅扫描当前文件的 --since 24h 可能会漏掉时间窗口前段的故障。 请让调度器同时读取活动文件和轮转文件，或者在扫描前拼接相关文件。
2. 多行堆栈跟踪需要首行。 解析器会将缩进的堆栈跟踪续行归到前一条已解析的日志行下。如果日志 收集器删掉了首行 Traceback 或 ERROR，剩下的堆栈帧就会变成无结构的上下文。
3. 预期中的错误可能造成误报。 重试、探测和健康检查可能会有意输出警告或连接失败信息。请将 错误簇视为“需要调查”的信号，而不是自动判定为事故。
4. 首次扫描大量历史日志可能导致输出过多。 先使用 --since 24h，检查报告，然后在需要时扩大 时间窗口。
5. 更改消息格式可能会拆分错误簇。 如果应用在部署期间更改了错误字符串，即使根本原因相同，部署 前后的故障也可能显示为两个错误簇。
6. 仅包含时间的日志取决于扫描日期。 12:30:45 ERROR ... 行不包含日期。对于历史文件，请优先使用完整时间戳。
7. 带逗号毫秒部分的 Python 日志行会导致 --since 静默失效。 格式为 2026-07-06 12:30:45,123 INFO module: ... 的行（Hermes agent/gateway/errors 日志）与内置时间戳正则表达式不匹配。它们会回退到非结构化解析，timestamp=null，因此 --since 无法过滤这些行， 整个未轮转文件都会被扫描。症状：错误/traceback 计数远超真实时间窗口内的数量，每个错误簇都显示 "First: unknown / Last: unknown"，错误时间线显示 "No timestamped errors detected"，崩溃数也被夸大（每条堆栈跟踪续行都会被计为一次单独的崩溃）。修复方法： 对于 Hermes 配置文件日志，请使用带时间窗口的计数器 scripts/hermes_log_window.py（可处理逗号毫秒格式，并且仅通过统计 Traceback (most recent call last) 首行来对多行 traceback 去重）；从配置文件的 state.db 中提取技能使用/工具调用计数的方法，请参阅 references/hermes-profile-audit.md。
8. 技能使用次数不在 agent.log 中。 tool skill_view completed (0.05s, 13890 chars) 行不包含技能名称参数。请查询配置文件 state.db 的 messages 表——tool_calls JSON 列保存了完整参数。messages.timestamp 是 Unix epoch（REAL），而非 ISO 格式。可直接运行的代码片段请参阅 references/hermes-profile-audit.md。
9. 错误时间线按一天中的时刻分桶，而非按日期。 在跨多天的时间窗口（--since 7d）内，不同日期 08:00 的错误会合并到同一个 08:00 柱中。进行多天取证时，请使用带完整时间戳的错误簇；将时间线视为一天中各时段的分布。
10. 崩溃检测基于子字符串匹配。 崩溃正则表达式会匹配行内任意位置出现的 fatal 或 Exception 等词语，因此 INFO 行中提及这些词语（例如“重试在 TimeoutException 后成功”、“non-fatal warning”）也会被计为崩溃信号，并可能设置 has_anomalies。请将崩溃计数视为需要人工核查的线索；如果日志会在 INFO 级别正常提及异常，请调整正则表达式。

此技能不是什么

• 不是日志查看器：需要检查原始日志行时，请使用 tail、less 或日志 UI。
• 不是日志采集器：它不会将日志转发到存储或可观测性系统。
• 不是 SIEM：它不会关联身份、网络或安全事件。
• 不是实时监控：tail 是近期日志分析器，不是守护进程或告警服务。
• 不是根因判定工具：它会突出显示模式，帮助 Agent 或操作人员更快地进行调查。

验证清单

• 运行 python scripts/analyze_logs.py --help，确认子命令已加载。
• 扫描包含重复错误的合成日志，确认 has_anomalies 为 true。
• 根据扫描 JSON 渲染 Markdown，确认所有异常部分均已显示。
• 在此技能目录中运行 python -m pytest tests/test_analyze_logs.py -v。
• 在此技能目录中运行 python -m pytest tests/test_state_failures.py -v（state.db 故障率监控；尖峰回归测试——仅提及错误词语的内容不得计为故障——位于此处）。
• 用于 cron 时，使用 --quiet 测试无异常日志，并确认 stdout 为空且退出代码为 0。
• 用于 state.db cron 时，针对运行中的配置文件 DB 执行 python scripts/state_failures.py --quiet，确认在时间窗口内没有故障时退出代码为 0 且不打印任何内容。