Rédaction d'alertes de suivi d'erreurs

Rédiger une alerte de suivi d'erreurs est un problème de routage, non de mesure. Les événements déclencheurs existent déjà et se déclenchent sur des conditions réelles dans le pipeline d'ingestion — votre rôle est de choisir le bon déclencheur pour l'intention de l'utilisateur, de dédupliquer par rapport à ce qui est déjà configuré, et de connecter une destination sur laquelle il peut réellement agir.

Quand utiliser cette compétence

• L'utilisateur demande de configurer des alertes / notifications pour les erreurs ou exceptions dans son projet.
• L'utilisateur souhaite un ensemble d'alertes de démarrage après activation du suivi d'erreurs.
• L'utilisateur colle un lien vers un problème et demande « notifiez-moi quand cela se reproduit » — généralement _reopened avec un filtre de propriété par problème.

Quand ne pas utiliser cette compétence

• Ajuster le détecteur de pics lui-même (multiplicateur, fenêtre, seuil). Cela se fait via l'endpoint de configuration du détecteur de pics et n'est pas exposé via MCP actuellement.
• Enquêter sur un incident actif — interrogez directement le problème / ses événements via posthog:query-error-tracking-issue et posthog:query-error-tracking-issue-events au lieu de rédiger d'autres alertes pendant que l'incident est actif.
• Configurer des alertes seuil de volume (nombre d'événements $exception sur une fenêtre). C'est une alerte de style logs et ce n'est pas du ressort d'ici — les alertes de suivi d'erreurs utilisent les événements du cycle de vie à la place.

Outils

Événements déclencheurs — en choisir exactement un par alerte

Il y a trois événements du cycle de vie. Chacun a un compromis « bruit vs urgence » différent — en choisir un mauvais est la cause la plus courante de fatigue d'alerte ici.

Si l'utilisateur est vague (« alertez-moi sur les erreurs »), défaut à _spiking. C'est le déclencheur le plus dense en signal et le moins susceptible de causer une fatigue d'alerte. Confirmez explicitement avant de procéder.

Flux de travail

1. Confirmer l'intention

Vous avez besoin de trois choses de l'utilisateur avant de créer quoi que ce soit :

• Quel événement déclencheur. S'il n'est pas spécifié, recommandez _spiking et demandez une confirmation. Ne le choisissez pas silencieusement.
• Quel canal. Nom du canal Slack, URL webhook, équipe Linear, etc. Ne codez jamais en dur un canal de production. Si l'utilisateur dit « le canal dev », demandez l'id ou le nom exact du canal.
• Quelle portée. Tous les problèmes (le plus courant), ou limité à un problème spécifique / type d'exception / assigné.

2. Dédupliquer par rapport aux alertes existantes

Appelez posthog:error-tracking-alerts-list. Filtrez la réponse côté client par filters.events[].id.

• Si une alerte existe pour le même événement remis au même canal, arrêtez. Dites à l'utilisateur qu'elle existe déjà et demandez s'il veut changer quelque chose (auquel cas utilisez error-tracking-alerts-partial-update) ou si vous devez sauter.
• Plusieurs alertes sur le même événement pour le même canal produisent des messages Slack en double — l'utilisateur ne le veut presque jamais.
• Plusieurs alertes sur le même événement pour différents canaux (p. ex. une pour #oncall, une pour le webhook oncall) c'est bien et parfois intentionnel. Confirmez.

La recommandation « alertes configurées » de PostHog n'inspecte que filters.events — ajouter des filters.properties par problème n'affecte pas le statut que la carte de recommandations rapporte.

3. Choisir l'intégration

Pour Slack :

1. posthog:integrations-list avec kind=slack → choisir l'id d'intégration (un entier).
2. posthog:integrations-channels-retrieve avec cet id → choisir l'id de canal (p. ex. C0123ABC). Les noms de canaux comme "#oncall" sont acceptés mais les ids de canal sont préférés — ils survivent aux renommages.

Pour webhook : l'utilisateur fournit une seule URL https://. Refusez les URL http://.

Pour Linear / GitHub / GitLab : confirmez que l'intégration est connectée via posthog:integrations-list d'abord, puis demandez à l'utilisateur dans quel projet / repository / équipe lancer les problèmes.

4. Créer l'alerte

Appelez posthog:error-tracking-alerts-create avec :

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

Le payload canonique Slack blocks pour chaque événement se trouve dans references/block-templates.md. Copiez le bloc correspondant tel quel — il correspond à l'assistant d'alerte intégré, donc les alertes créées par l'agent ressemblent à des alertes créées par l'interface utilisateur.

Pour la portée par problème — created / reopened uniquement, les événements de pics ne comportent aucune propriété d'exception — ajoutez à filters :

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

Autres filtres de propriété utiles : $exception_types (noms de classe d'exception, un tableau), name (titre du problème). Voir references/event-triggers.md pour la surface de propriété complète par événement.

5. Vérifier

Restituez l'alerte à l'utilisateur avec : nom, événement déclencheur (lisible par l'homme), destination, et un aperçu d'une ligne du corps du message. Ne restituez pas les ids d'espace de travail Slack ou les URL webhook — ceux-ci sont sensibles. Dites à l'utilisateur comment désactiver : « vous pouvez suspendre cette alerte en définissant enabled: false via error-tracking-alerts-partial-update ou en la basculant dans l'interface utilisateur des destinations ».

Convention de nommage

Utilisez <trigger> · <canal> (auto) pour que l'utilisateur puisse scanner sa liste d'alertes et repérer les entrées créées par l'agent. Exemples :

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

N'utilisez pas le titre du problème dans le nom — les alertes peuvent correspondre à de nombreux problèmes, et le titre devient obsolète une fois que le problème évolue.

Règles d'économie de jetons

• Un appel posthog:error-tracking-alerts-list au départ, pas par candidat.
• Réutilisez une seule recherche d'intégration pour plusieurs alertes allant au même espace de travail.
• Confirmez le canal / l'URL avec l'utilisateur avant de créer chaque alerte. Ne créez jamais par lot des alertes vers une destination que l'utilisateur n'a pas nommée explicitement.
• Plafonnez l'itération à 1 tour par alerte. Si l'utilisateur veut trois alertes, c'est trois appels de création — pas trois appels de création par alerte.

Sortie

Rapportez ce que vous avez fait, sous cette forme :

• Pour chaque alerte déployée : nom, événement déclencheur, destination (nom du canal ou hôte webhook — jamais l'URL complète), état activé.
• Pour chaque alerte ignorée : déclencheur + canal + pourquoi (existe déjà, utilisateur décliné, intégration manquante).
• Tout ce que l'utilisateur doit faire ensuite : activer la config du détecteur de pics (s'il a choisi _spiking et que le détecteur n'a pas été activé), connecter les source maps (pour que les liens de stack trace de l'alerte se résolvent), ou régler les filtres d'alerte après l'avoir observée pendant une journée.

Compétences connexes

• triaging-error-issues — déterminer quels problèmes importent réellement avant de rédiger des alertes pour eux
• investigating-error-issue — approfondir un problème pour lequel une alerte s'est déclenchée
• authoring-log-alerts — le même travail d'alerte, mais pour les lignes de log au lieu des exceptions