authoring-log-alerts

编写日志告警

编写告警是一个_测量_问题，而不是猜测问题。你不必面面俱到——而是要针对重要服务上的真实生产模式，设定每周触发 0–3 次的阈值。

适用场景

• 用户要求为项目“设置告警”或“推荐告警”。
• 用户想评估某项服务是否产生了适合设置告警的信号。
• 用户刚启用日志告警，希望先创建一组基础告警。

不适用场景

• 调整已有告警——这是另一项工作（使用 posthog:logs-alerts-events-list 检查触发／恢复频率，并使用 posthog:logs-alerts-partial-update 进行调整）。
• 调查正在发生的事件——使用 posthog:query-logs 拉取日志行；不要在事件发生期间编写告警。

工具

工具	用途	所处步骤
posthog:logs-services	时间范围内排名前 25 的服务，包含 log_count、error_count、error_rate 和 sparkline。	步骤 1——分类排查。
posthog:logs-attributes-list / posthog:logs-attribute-values-list	查找键／值，以使用更精确的筛选条件。	步骤 2，可选。
posthog:logs-count-ranges	按时间段自适应统计筛选条件的数量。	步骤 3——建立基线。
posthog:logs-alerts-simulate-create	使用完整状态机，对照 -7d 历史数据回放告警草稿配置。	步骤 4——验证。
posthog:logs-alerts-create	保存告警。	步骤 5——发布。
posthog:logs-alerts-destinations-create	将告警连接到 Slack、webhook 或 Microsoft Teams。	步骤 5：发布。

编写告警时，不要调用 posthog:query-logs。你需要的是分布数据，而不是日志行。只有在用户最后要求“给我看看可能触发告警的日志样本”时，才使用 posthog:query-logs——limit: 10 就足够了。

工作流

1. 分类排查——挑选候选服务

调用 posthog:logs-services，查询最近 24 小时的数据，不添加筛选条件。响应最多包含 25 个服务，并附带 sparkline，因此数据量小且有限。

满足以下两项的服务可作为候选：

• log_count 不低（24 小时内 ≥ ~1k——较安静的服务产生的信号不足以设置告警）。
• error_rate 不为零，或者用户明确指定了该服务。

跳过日志量大但 error_rate == 0 的服务，除非用户想要基于日志量变化的告警（例如“如果 api-gateway 突然停止产生日志，就通知我”）。日志量下限告警使用 threshold_operator: below，需要采用不同的判断方式——参见 references/volume-floor-alerts.md。

如果用户指定了某项服务，即使没有错误信号，也应将其视为候选服务。

2. （可选）缩小筛选范围

如果某项服务存在多种错误子类型，针对“所有错误”设置告警通常范围太广。使用 posthog:logs-attributes-list（尝试 attribute_type: log）和 posthog:logs-attribute-values-list 查找区分属性——常见属性包括 http.status_code、error.type、k8s.container.name。将缩小范围的筛选条件加入告警草稿。

保持简单：一个严重性筛选条件，加上一两个属性筛选条件就足够了。多条件筛选更难判断，而且很少能提高精确度。

3. 基线——分析候选项过去 7 天的特征

使用候选项的筛选条件调用 posthog:logs-count-ranges，设置 dateRange: { date_from: "-7d" }，并将 targetBuckets 设为 24（每个桶约 7 小时）。响应会提供各桶的计数。

不要凭直觉估算百分位数，也不要手动按告警窗口缩放阈值。 将计数范围响应传入辅助脚本：

echo '<count-ranges JSON>' | python3 scripts/baseline_stats.py --window-minutes 5

脚本会返回：

{
  "n_buckets": 12,
  "bucket_minutes": 420.0,
  "alert_window_minutes": 5,
  "stats": { "p50": 12.0, "p95": 71.25, "p99": 126.25, "max": 140 },
  "suggested_threshold_count": 5,
  "rationale": "max(p99=126.25, median*3=36.0, floor=5) scaled from 420m bucket to 5m window",
  "health": []
}

将 suggested_threshold_count 作为初始阈值。查看 health：

health 标记	含义	操作
sparse:N_of_M_buckets	7 天基线中的非空桶过少。	扩大筛选范围、将时间延长至 -30d，或跳过。
empty	所有桶的计数均为零。	跳过——没有信号。
spiky	max 是 p95 的 10 倍以上。	计数阈值告警效果良好。继续。
flat	p95 ≈ p50。	请谨慎处理——回溯期内可能没有发生事件，或指标过于平稳。尝试延长回溯期，或跳过。
[]（空）	分布健康。	继续。

4. 起草并模拟

从以下默认值中选择初始草案——推理依据请参阅 references/threshold-defaults.md：

设置	默认值	说明
threshold_count	脚本返回的 suggested_threshold_count	已按告警窗口缩放。
threshold_operator	above	仅在设置量级下限告警时使用 below。
window_minutes	5	允许值：5、10、15、30、60。必须与传入脚本的值一致。
evaluation_periods	3	N-of-M 中的 M。
datapoints_to_alarm	2	N-of-M 中的 N。2-of-3 可减少单个噪声桶导致的频繁触发。
cooldown_minutes	30	两次通知（触发或恢复）之间的最短间隔。

使用这些设置和 date_from: "-7d" 调用 posthog:logs-alerts-simulate-create。响应会提供 fire_count 和 resolve_count。

5. 迭代 — 三轮后决定发布或跳过

目标：fire_count 在 -7d 内介于 0 到约 3 之间。如果超出此范围：

结果	调整
7d 内 fire_count = 0，并且 基线有尖峰	将 threshold_count 调低至接近脚本中的 stats.p95，或改为 2 次中触发 1 次。
fire_count = 0，并且 基线平坦	该服务没有可用于告警的信号。跳过它，并记录原因。
fire_count > 5	将 threshold_count 调高至接近脚本中的 stats.max，或改为 5 次中触发 3 次，以使用更平滑的时间窗口。
fire_count 合适，但 resolve_count 始终与 fire_count 不匹配	冷却时间过长，或底层状态确实持续时间较长。目前可以接受。

调整阈值时，请读取脚本 stats 块中的值 — 切勿手动重新计算百分位数。

每个候选项最多迭代 3 次 simulate 调用。如果 3 轮后仍无法达到目标范围，则说明指标有问题 — 过滤条件过宽、时间窗口不合适，或该服务确实没有符合阈值形态的信号。记录原因并继续处理下一个。

6. 发布 — 创建告警并附加通知目标

草稿通过模拟后：

1. 使用经过验证的配置调用 posthog:logs-alerts-create。名称可以采用 <service> error rate (auto) 这样的格式，让用户一眼就能看出哪些告警来自此技能。

2. 调用 posthog:logs-alerts-destinations-create，将告警连接到通知目标。**没有通知目标的告警不会发送通知。**支持的通知目标字段：

   • Slack：type: "slack"、slack_workspace_id 和 slack_channel_id。slack_channel_name 为可选项。
   • Webhook：type: "webhook" 和 webhook_url。
   • Microsoft Teams：type: "teams" 和 webhook_url。

   附加通知目标前，务必向用户确认频道名称或 Webhook URL。未经明确确认，切勿将自动生成的告警连接到生产频道。如果用户不确定，建议先使用流量较低的测试频道发送前几条告警。

如果用户希望创建处于 enabled: false 状态的告警，以便先审核再启用，请在调用 -create 时传入 enabled: false，并告知创建了多少个草稿。

过滤条件格式 — 必填

posthog:logs-alerts-create 的 filters 字段接受 LogsViewerFilters 的一个子集，且必须至少包含以下一项：

• severityLevels — ["trace","debug","info","warn","error","fatal"] 列表
• serviceNames — 服务名称字符串列表
• filterGroup — 属性过滤条件组

相同格式也要用于 posthog:logs-alerts-simulate-create 的 filters 字段。模拟过滤条件必须与告警过滤条件完全一致 — 否则模拟测试的就不是你要发布的告警。

最低限度示例：

{
  "severityLevels": ["error", "fatal"],
  "serviceNames": ["api-gateway"]
}

Token 使用规则

• 开始时调用一次 posthog:logs-services，而不是每个候选项都调用。
• 每个候选项调用一次 posthog:logs-count-ranges，并设置 targetBuckets: 24。编写期间不要超过 30。
• 每个候选项最多调用 3 次 posthog:logs-alerts-simulate-create。
• 编写循环期间不调用 posthog:query-logs。
• 优先报告少量经过充分验证的告警，而不是大量未经验证的草稿。

输出

按以下格式报告所做的工作：

• 对于每个已发布的告警：名称、过滤条件、阈值、7d 内模拟的 fire_count、通知目标。
• 对于每个跳过的候选项：服务名称 + 原因（基线平坦、无法达到阈值、流量低）。
• 模拟调用总次数、创建的告警总数。

用户应能根据这些信息判断是否要在草稿正式启用前将其禁用。

相关技能

• investigating-logs — 在针对服务设置告警前了解其基线，并在告警触发后进行调查
• authoring-error-tracking-alerts — 针对异常而非日志行设置告警