Authoring Error Tracking Alerts

Authoring error tracking alerts

Authoring an error tracking alert is a routing problem, not a measurement problem. The trigger events already exist and fire on real conditions in the ingestion pipeline — your job is to pick the right trigger for the user's intent, dedupe against what's already configured, and wire a destination they can actually act on.

When to use this skill

• The user asks to set up alerts / notifications for errors or exceptions in their project.
• The user wants a starter set of alerts after enabling error tracking.
• The user pastes an issue link and asks "notify me when this happens again" — usually _reopened with a per-issue property filter.

When not to use this skill

• Tuning the spike detector itself (multiplier, window, threshold). That lives behind the spike detection config endpoint and is not exposed via MCP today.
• Investigating an active incident — query the issue / its events directly via posthog:query-error-tracking-issue and posthog:query-error-tracking-issue-events instead of authoring more alerts mid-fire.
• Configuring volume-threshold alerts (count of $exception events over a window). That's a logs-style alert and is not in scope here — error tracking alerts ride the lifecycle events instead.

Tools

Trigger events — pick exactly one per alert

There are three lifecycle events. Each has a different "noise vs urgency" trade-off — picking the wrong one is the most common cause of alert fatigue here.

If the user is vague ("alert me on errors"), default to _spiking. It's the most signal-dense trigger and the least likely to cause alert fatigue. Confirm explicitly before proceeding.

Workflow

1. Confirm intent

You need three things from the user before creating anything:

• Which trigger event. If unspecified, recommend _spiking and ask for confirmation. Do not silently pick one.
• Which channel. Slack channel name, webhook URL, Linear team, etc. Never hardcode a production channel. If the user says "the dev channel", ask for the exact channel id or name.
• Which scope. All issues (most common), or scoped to a specific issue / exception type / assignee.

2. Dedupe against existing alerts

Scan every destination before you decide. The endpoint is paginated and defaults to 100 rows per page, so a single default call misses older alerts on a project with hundreds of destinations.

Call posthog:error-tracking-alerts-list with type: ["internal_destination"] and limit: 1000. If the response still carries a non-null next, keep paging with offset until next is null. Then filter the collected rows client-side by filters.events[].id and by any per-issue scope in filters.properties.

The list response carries no inputs, so it does not tell you which channel or URL a row delivers to. Read the destination off name and description instead — the naming convention below puts the channel in the name. When a row matches on event and scope but its name does not say where it delivers, do not guess: show the user the matching names and ask whether one of them is the alert they mean.

• If an alert exists for the same event delivering to the same channel with the same scope, stop. Tell the user it already exists and ask whether they want to change anything (in which case use error-tracking-alerts-partial-update) or skip.
• Multiple alerts on the same event for the same channel produce duplicate Slack messages — the user almost never wants this.
• Multiple alerts on the same event for different channels (e.g. one for #oncall, one for the oncall webhook) is fine and sometimes intentional. Confirm.
• Multiple alerts on the same event and channel but different scopes (e.g. two _reopened alerts each pinned to a different $exception_issue_id) are not duplicates. Confirm before adding. Note that a scoped alert and an all-issues alert to the same channel both fire on the scoped issue.

PostHog's "alerts configured" recommendation only inspects filters.events — adding per-issue filters.properties does not affect the status the alerts banner reports.

3. Pick the integration

For Slack:

1. posthog:integrations-list with kind=slack → pick the integration id (an integer).
2. posthog:integrations-channels-retrieve with that id → pick the channel id (e.g. C0123ABC). Channel names like "#oncall" are accepted but channel ids are preferred — they survive renames.

For webhook: the user supplies a single https:// URL. Refuse http:// URLs.

For Linear / GitHub / GitLab: confirm the integration is connected via posthog:integrations-list first, then ask the user which project / repository / team to file issues into.

4. Create the alert

Call posthog:error-tracking-alerts-create with:

jsonCopy code
{
  "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": [...] }
  }
}

The canonical Slack blocks payload for each event lives in references/block-templates.md. Copy the matching block verbatim — it matches the in-product alert wizard, so agent-created alerts look identical to UI-created ones.

For per-issue scoping — created / reopened only, spiking events carry no exception properties — add to filters:

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

Other useful property filters: $exception_types (exception class names, an array), name (issue title). See references/event-triggers.md for the full property surface per event.

5. Verify

Echo the alert back to the user with: name, trigger event (human-readable), destination, and a one-line preview of the message body. Do not echo Slack workspace ids or webhook URLs — those are sensitive. Tell the user how to disable: "you can pause this alert by setting enabled: false via error-tracking-alerts-partial-update or by toggling it in the destinations UI."

Naming convention

Use <trigger> · <channel> (auto) so the user can scan their alert list and spot agent-created entries. Examples:

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

Do not use the issue title in the name — alerts can match many issues, and the title becomes stale once the issue evolves.

Token-economy rules

• One complete posthog:error-tracking-alerts-list scan up front, not per candidate. The scan is complete only when next is null — page through it once and reuse the collected rows for every candidate.
• Reuse a single integration lookup for multiple alerts going to the same workspace.
• Confirm the channel / URL with the user before creating each alert. Never batch-create alerts to a destination the user has not explicitly named.
• Cap iteration at 1 round per alert. If the user wants three alerts, that's three create calls — not three create calls per alert.

Output

Report what you did, in this shape:

• For each shipped alert: name, trigger event, destination (channel name or webhook host — never the full URL), enabled state.
• For each skipped alert: trigger + channel + why (already exists, user declined, missing integration).
• Anything the user should do next: enable the spike detection config (if they picked _spiking and the detector hasn't been turned on), wire up source maps (so the alert's stack trace links resolve), or tune the alert filters after watching it for a day.

Related skills

• triaging-error-issues — work out which issues actually matter before wiring alerts for them
• investigating-error-issue — deep-dive an issue an alert fired for
• authoring-log-alerts — the same alerting job, but for log lines instead of exceptions