investigating-logs

调查日志

调查的关键在于逐步缩小范围：先汇总，再阅读。 一次 posthog:logs-patterns 调用，就能将数百万行压缩为最多 200 个模板； 一次 posthog:logs-patterns-diff 调用，则能直接回答“现在和之前有什么不同”。 原始行（posthog:query-logs）是调查的最后一步，绝不是第一步。

何时使用此技能

• “检查日志”／“服务 X 是否正常？”／“我的部署（或模型升级、配置更改、迁移）是否导致了问题？”
• “错误为什么变多了？”／“解释这个峰值”／事件分类——“发生了什么变化？”
• “这个服务在记录什么？”——了解不熟悉或噪声较多的日志流。
• 查找其他地方报告的问题（告警、错误跟踪问题、用户投诉）的日志证据。

何时不使用此技能

• 创建或调整日志告警——请使用 authoring-log-alerts。
• 分析产品事件、人员或洞察数据——请使用 querying-posthog-data。
• HogQL 可通过 posthog:execute-sql 访问 logs 表，但不要通过它来调查日志： 手写针对日志的 SQL 经常会触及读取字节数上限，并重复实现下方工具一次低成本调用就能完成的工作。 仅在极少数需要将日志衍生事实与非日志数据联接的情况下使用 SQL。

工具

工具	用途
posthog:logs-services-create	按 log_count、error_count、error_rate 和 sparkline 显示排名前 25 的服务。用于了解概况。
posthog:logs-patterns	挖掘一个时间窗口内的消息模板，并按频率排序。“这个日志流在说什么？”
posthog:logs-patterns-diff	对比两个时间窗口内的模板：新增／频率变化／消失。“发生了什么变化？”
posthog:logs-count / posthog:logs-count-ranges	筛选条件对应的总数和分时段计数。先定位数量变化，再提取日志行。
posthog:logs-sparkline-query	按严重性或服务细分的时间序列数量（唯一提供细分维度的分桶视图）。
posthog:logs-facet-values-create	筛选条件下严重性／服务（或资源属性）的分布。
posthog:logs-attributes-list / posthog:logs-attribute-values-list	在构建筛选条件前，发现属性键和值。
posthog:query-logs	原始行。每次深入调查的终点，不是任何调查的起点。

每个工具自身的说明都记录了其参数和响应格式——调用前请先阅读。

根据问题类型选择工作流

“状态正常吗？”——部署后／变更后验证

用户更改了某些内容（部署、模型升级、配置、迁移），并想知道日志是否依然正常。

1. 确定变更时间和受影响的服务。如果用户尚未说明，请询问；没有时间边界，差异就毫无意义。
2. 使用 posthog:logs-services-create 了解情况：服务是否仍在记录日志，目前的 error_rate 是多少？ 服务不再产生日志和开始报错一样，都会导致验证失败。
3. 使用 posthog:logs-patterns-diff，将 query.dateRange 设为从变更时间到现在，并将 baselineDateRange 设为变更前可比较的时间段，同时限定 serviceNames。 变更后立刻出现新的 error/fatal 模板，是典型的回归迹象； 现有错误模板的 rate_ratio 大幅变化，则是第二个需要检查的问题。
4. 使用 posthog:logs-count-ranges 检查变更边界前后的日志量是否连续： 即使消息内容看起来没变，速率不连续（崩溃循环、重启风暴、日志静默）也会在这里显现。
5. 只深入检查可疑项：通过 posthog:query-logs，使用每个可疑模式的 match_regex 查看原始日志行。

要判定通过，必须同时满足三项：没有新的错误模板、错误的 rate_ratio 没有大幅变化、日志量连续。 说明你比较的是哪些时间段——“状态正常”这一结论的可靠性取决于基线。

“解释一下这次峰值”

1. 定位峰值：对用户指定的时间段运行 posthog:logs-count-ranges，然后递归细分日志密集的时间桶——将每个时间桶的 date_from／date_to 作为下一次调用的参数。递归 3–4 层后停止。
2. 解释峰值：使用 posthog:logs-patterns-diff，将峰值时间段设为 query.dateRange，并将峰值前的时间段设为 baselineDateRange。排名靠前的 new 和 rate_shift 条目就是原因。不要分别检查两个时间段再手动比较——一次调用就能完成差异分析。

事件排查——“哪里出问题了？”

首先使用 posthog:logs-patterns-diff：将事件时间段与紧邻其前的已知正常时间段进行比较（或省略基线，以使用上周的同一时间段）。可疑项是 new 条目和 rate_ratio 变化最大的条目；对每个条目查看原始日志行。 如果不知道出问题的是哪个服务，先使用 posthog:logs-facet-values-create，在 severityLevels: ["error", "fatal"] 条件下按 service_name 分面查找。

“这段日志流在说什么？”——不熟悉的服务

使用 posthog:logs-patterns 查看过去一小时的日志，并限定服务范围。根据 estimated_count 和 severity_counts 中非零的错误占比，扫描日志模板。只有在找不到答案时，才扩大时间范围或添加 searchTerm。

已知目标——特定消息、属性或人员

如果目标已经明确（错误字符串、请求 ID、distinct_id），就跳过模式分析： 使用 posthog:logs-attributes-list／posthog:logs-attribute-values-list 查找正确的键， 使用 posthog:logs-count 估算结果数量，然后通过 posthog:query-logs 拉取日志行。

让调查保持严谨且经济的规则

• 确认目标服务后，每次调用都应指定 serviceNames（或资源属性筛选条件）。 不指定范围的调用会扫描整个团队的数据流，并耗尽模式采样预算。
• posthog:query-logs 必须显式指定 query.dateRange ——省略该参数会返回 400 错误，不会采用默认时间范围。
• 模式计数是采样估算值（sampled: true）；出现频率低于约每 10,000 行 1 次的模板可能无法显示。 未发现罕见模板，并不能证明它已经停止出现。
• 如果差异中有大量 new 条目，在相信它们之前先检查 baseline.total_count — 基线过小或为空（例如刚开始记录日志）会让所有内容看起来都是新增的。
• severityLevels 会将六个规范的小写级别与 severity_text 精确匹配。 按级别筛选后没有结果 → 使用 posthog:logs-attribute-values-list { key: "severity_text" } 检查存储的值。
• 预算：调用一次 services；每对时间窗口最多调用一次 patterns-diff；使用 3–4 个 count-ranges 级别； 仅对已确认的可疑项调用 query-logs，且 limit ≤ 100。

输出

先给出结论，再列出证据：

• 结论：健康 / 已退化 / 无法确定，并注明对比的时间窗口。
• 可疑项（如有）：模板、分类（new / rate_shift）、估算计数或 rate_ratio、服务，以及 1–2 条原始样例日志。
• 检查了什么，以及未检查什么：覆盖的服务、时间窗口，以及影响判断可信度的任何采样或基线注意事项。

用户应能根据结论采取行动，而无需重新运行调查。

相关技能

• authoring-log-alerts — 将结论背后的检查转化为持续、低噪声的告警
• exploring-apm-traces — 沿着可疑日志行，查看与其相关的请求跟踪