authoring-error-tracking-alerts

编写错误跟踪告警

编写错误跟踪告警是一个_路由_问题，而非测量问题。触发事件已经存在，并且会在数据摄取管道中遇到真实条件时触发——你的任务是根据用户意图选择合适的触发器、与已有配置去重，并连接到用户实际可以采取行动的目标。

何时使用此技能

• 用户要求为其项目设置错误或异常告警／通知。
• 用户启用错误跟踪后，希望先配置一组基础告警。
• 用户贴出问题链接并询问“下次发生时通知我”——通常应使用 _reopened，并设置按问题筛选的属性条件。

何时不使用此技能

• 调整峰值检测器本身（倍数、时间窗口、阈值）。这需要通过峰值检测配置端点完成，目前 MCP 尚未开放该功能。
• 调查正在发生的事故——应直接通过 posthog:query-error-tracking-issue 和 posthog:query-error-tracking-issue-events 查询问题／相关事件，而不是在告警触发期间继续编写告警。
• 配置数量阈值告警（某个时间窗口内 $exception 事件的数量）。这属于日志类型的告警，不在此处的范围内——错误跟踪告警基于生命周期事件触发。

工具

工具	用途	适用步骤
posthog:error-tracking-alerts-list	列出现有告警（分页）；创建前先去重。	步骤 2——去重。
posthog:integrations-list	查找用户的 Slack 工作区 ID（按 kind=slack 筛选）。	步骤 3——选择频道。
posthog:integrations-channels-retrieve	列出工作区的 Slack 频道。	步骤 3——选择频道。
posthog:error-tracking-alerts-create	创建告警（类型为 internal_destination 的 HogFunction）。	步骤 4——发布。
posthog:error-tracking-alerts-partial-update	切换、重命名或修改现有告警。	调整告警时使用，不用于创建。
posthog:error-tracking-alerts-delete	软删除告警。	用户要求“移除”时使用。

触发事件——每个告警只能选择一个

生命周期事件有三种。每种事件在“噪声与紧迫性”之间的权衡各不相同——选错是造成告警疲劳最常见的原因。

事件	触发时机	适用场景
$error_tracking_issue_created	某个全新问题首次出现时。	适用于小型项目，或每种新错误都确实值得关注的项目。大型或噪声较多的项目会被告警淹没。
$error_tracking_issue_reopened	之前已解决的问题再次开始产生事件时。	用于捕获已经有人排查过的问题的回归。这是最稳妥的“如果问题再次出现，我想知道”触发事件。
$error_tracking_issue_spiking	峰值检测器标记出某个问题的异常事件量时。	适用于基准事件量较高的生产项目。阈值／倍数由整个项目共享——使用前请检查峰值配置。

如果用户的说法比较含糊（“有错误就提醒我”），默认选择 _spiking。这个触发事件的有效信号密度最高，也最不容易造成告警疲劳。继续之前请明确确认。

工作流

1. 确认意图

创建任何内容之前，需要向用户确认以下三项：

• 触发事件。 如果用户未指定，请推荐 _spiking 并征求确认。不要默默替用户选择。
• 通知渠道。 Slack 频道名称、Webhook URL、Linear 团队等。切勿将生产频道硬编码。如果用户说“开发频道”，请询问准确的频道 ID 或名称。
• 范围。 所有问题（最常见），或限定到特定问题／异常类型／负责人。

2. 与现有告警去重

在作出决定前，扫描所有目标。该端点采用分页，默认每页返回 100 行，因此对于有数百个目标的项目，只调用一次默认接口会漏掉较早的告警。

调用 posthog:error-tracking-alerts-list，并传入 type: ["internal_destination"] 和 limit: 1000。如果响应中 next 仍不为 null，则继续使用 offset 翻页，直到 next 为 null。然后在客户端按 filters.events[].id 和 filters.properties 中的任意单问题范围筛选收集到的行。

列表响应不包含 inputs，因此无法告知你某一行会投递到哪个渠道或 URL。请改为根据 name 和 description 判断目标——下方的命名约定会在名称中标明渠道。如果某一行的事件和范围匹配，但名称未说明投递位置，不要猜测：向用户展示匹配的名称，并询问其中是否有他们指的告警。

• 如果存在一个告警，其事件相同、投递到相同渠道且范围相同，则停止。告诉用户该告警已存在，并询问他们是否想要修改（此时使用 error-tracking-alerts-partial-update）或跳过。
• 同一事件的多个告警投递到同一渠道会产生重复的 Slack 消息——用户几乎不会希望如此。
• 同一事件的多个告警投递到不同渠道（例如，一个投递到 #oncall，另一个投递到 oncall webhook）是可以的，有时也是有意为之。请确认。
• 同一事件和渠道的多个告警若范围不同（例如，两个 _reopened 告警分别固定到不同的 $exception_issue_id），则不算重复。添加前请确认。请注意，范围限定告警和针对所有问题的告警若投递到同一渠道，都会针对范围内的问题触发。

PostHog 的“已配置告警”建议只检查 filters.events——添加按问题筛选的 filters.properties 不会影响告警横幅显示的状态。

3. 选择集成

对于 Slack：

1. 调用 posthog:integrations-list 并设置 kind=slack → 选择集成 id（整数）。
2. 使用该 id 调用 posthog:integrations-channels-retrieve → 选择频道 id（例如 C0123ABC）。也接受 "#oncall" 这样的频道名称，但更推荐使用频道 id——频道重命名后它们仍然有效。

对于 webhook：用户提供一个 https:// URL。拒绝 http:// URL。

对于 Linear / GitHub / GitLab：先通过 posthog:integrations-list 确认已连接集成，然后询问用户要将问题提交到哪个项目 / 仓库 / 团队。

4. 创建告警

使用以下参数调用 posthog:error-tracking-alerts-create：

{
  "type": "internal_destination",
  "template_id": "template-slack",
  "name": "<short, channel-attributed name>",
  "enabled": true,
  "filters": {
    "events": [{ "id": "$error_tracking_issue_created", "type": "events" }]
  },
  "inputs": {
    "slack_workspace": { "value": <slack_integration_id_int> },
    "channel": { "value": "<channel_id>" },
    "text": { "value": "..." },
    "blocks": { "value": [...] }
  }
}

每个事件对应的规范 Slack blocks 负载位于 references/block-templates.md。逐字复制匹配的区块——它与产品内的告警向导一致，因此 Agent 创建的告警看起来会与通过 UI 创建的告警完全相同。

对于按问题设定范围——仅适用于 created / reopened，尖峰事件不包含异常属性——请添加到 filters：

"properties": [
  { "key": "$exception_issue_id", "value": "<issue_uuid>", "operator": "exact", "type": "event" }
]

其他有用的属性筛选器：$exception_types（异常类名称数组）、name（问题标题）。有关各事件的完整属性范围，请参阅 references/event-triggers.md。

5. 验证

向用户复述告警内容，包括：名称、触发事件（易读形式）、目标，以及消息正文的一行预览。不要复述 Slack 工作区 id 或 webhook URL——这些信息很敏感。告知用户如何停用：“你可以通过 error-tracking-alerts-partial-update 将 enabled: false，或在目标 UI 中切换开关，来暂停此告警。”

命名规范

使用 <触发条件> · <频道> (auto)，方便用户浏览提醒列表并识别由 Agent 创建的条目。 例如：

• Issue spiking · #oncall (auto)
• Issue reopened · #regressions-webhook (auto)
• Issue created · Linear/Eng (auto)

不要在名称中使用问题标题——提醒可能匹配多个问题，而且问题演变后标题会过时。

Token 经济原则

• 开始时完整扫描一次 posthog:error-tracking-alerts-list，而不是针对每个候选项分别扫描。只有在 next 为 null 时，扫描才算完整——将所有页面翻完一次，并对每个候选项重复使用收集到的行。
• 多个提醒发送到同一工作区时，重复使用同一次集成查询。
• 创建每个提醒前，先与用户确认频道 / URL。绝不要批量创建发送到用户未明确指定目标的提醒。
• 每个提醒最多迭代 1 轮。如果用户想要 3 个提醒，就调用 3 次创建工具——而不是每个提醒调用 3 次。

输出

按以下格式报告你完成的工作：

• 对于每个已创建的提醒：名称、触发事件、目标位置（频道名称或 webhook 主机名——绝不提供完整 URL）、启用状态。
• 对于每个跳过的提醒：触发条件 + 频道 + 原因（已存在、用户拒绝、缺少集成）。
• 用户接下来需要做的事：启用 spike detection 配置（如果用户选择了 _spiking 且检测器尚未开启）、配置 source maps（以便提醒中的堆栈跟踪链接可以正常解析），或在观察一天后调整提醒筛选条件。

相关技能

• triaging-error-issues — 在为问题配置提醒之前，判断哪些问题确实重要
• investigating-error-issue — 深入调查触发提醒的问题
• authoring-log-alerts — 执行相同的提醒配置工作，但针对的是日志行，而非异常