Alerting Axiom

Vous gérez le alerting dans Axiom de bout en bout : notifiers pour le routage et monitors pour la détection.

Aperçu de l'API

URL de base : https://api.axiom.co/v2/ avec authentification Bearer token depuis .axiom.toml (racine du projet ou ~/.axiom.toml).

Monitors (/v2/monitors)

Notifiers (/v2/notifiers)

Prérequis

1. Exécutez scripts/setup
2. Assurez-vous que .axiom.toml contient un deployment :

[deployments.prod]
url = "https://api.axiom.co"
token = "xaat-your-token"
org_id = "your-org-id"

Scripts

Noyau :

• scripts/axiom-api <deploy> <method> <path> [body]

Scripts de monitor :

• scripts/monitor-list <deployment> [--json]
• scripts/monitor-get <deployment> <id>
• scripts/monitor-history <deployment> <id> <startTime> <endTime>
• scripts/monitor-create <deployment> <json-file>
• scripts/monitor-update <deployment> <id> <json-file>
• scripts/monitor-delete <deployment> <id>

Scripts de notifier :

• scripts/notifier-list <deployment> [--json]
• scripts/notifier-get <deployment> <id>
• scripts/notifier-create <deployment> <json-file>
• scripts/notifier-update <deployment> <id> <json-file>
• scripts/notifier-delete <deployment> <id>

Workflow recommandé

1. Créer d'abord le notifier.
2. Créer le monitor et définir notifierIds.
3. Valider le comportement du monitor avec monitor-history.
4. Itérer sur les seuils et la planification du monitor.

Workflow : Alerting de bout en bout

1. Exécutez scripts/setup.
2. Listez les notifiers existants avec scripts/notifier-list <deployment> et réutilisez-en un si approprié.
3. Si aucun notifier convenable n'existe, créez-en un avec scripts/notifier-create.
4. Créez ou mettez à jour le monitor avec notifierIds attachés.
5. Validez avec scripts/monitor-history <deployment> <id> <startTime> <endTime>.
6. Si le comportement est bruyant ou silencieux, ajustez threshold, rangeMinutes, intervalMinutes et les champs de déclenchement N-of-M.
7. Vérifiez l'historique après chaque modification.

Bonnes pratiques

• Configurez un canal par notifier.
• Utilisez emails (et non recipients) pour les payloads de notifier email.
• Préférez triggerAfterNPositiveResults/triggerFromNRuns pour les signaux bruyants.
• Utilisez bin() explicite dans les requêtes de monitor ; évitez bin_auto() pour la logique d'alerte.
• Pour les monitors basés sur des metrics, préférez mplQuery pour les définitions ; les réponses API peuvent inclure à la fois aplQuery et mplQuery.

Types de monitors et opérateurs

Types de monitors :

• Threshold
• MatchEvent
• AnomalyDetection

Opérateurs :

• Above
• Below
• AboveOrEqual
• BelowOrEqual
• AboveOrBelow

Référence des champs de monitor

Champs noyau :

• name : Nom du monitor lisible.
• type : Threshold, MatchEvent ou AnomalyDetection.
• aplQuery / mplQuery : Requête évaluée par le monitor.
• notifierIds : Tableau d'IDs de notifier à notifier.
• disabled : Si le monitor est désactivé.
• disabledUntil : Timestamp optionnel pour désactiver/mettre en pause temporaire.
• description : Description optionnelle du monitor.

Champs de threshold et évaluation :

• operator : Opérateur de comparaison de threshold.
• threshold : Valeur numérique du seuil.
• rangeMinutes : Fenêtre d'évaluation de la requête en minutes.
• intervalMinutes : Cadence d'évaluation en minutes.
• alertOnNoData : Si l'absence de données doit déclencher une alerte.
• triggerAfterNPositiveResults : Évaluations positives requises avant déclenchement.
• triggerFromNRuns : Total des exécutions d'évaluation considérées pour la logique N-of-M.

Champs de comportement avancé :

• resolvable : Si les alertes peuvent se résoudre automatiquement.
• notifyByGroup : Notifier par résultat clé/valeur du groupe.
• notifyEveryRun : Notifier à chaque évaluation positive.
• skipResolved : Ignorer l'envoi des notifications résolues.
• secondDelay : Délai (secondes) à tolérer pour les données tardives.

Champs spécifiques au type :

• columnName : Champ utilisé par certains monitors d'anomalie/value-anomaly.

Exemples minimaux de monitors valides

Threshold :

{
  "name": "High Error Count",
  "type": "Threshold",
  "aplQuery": "['logs'] | where status >= 500 | summarize count()",
  "operator": "Above",
  "threshold": 100,
  "rangeMinutes": 5,
  "intervalMinutes": 5,
  "notifierIds": ["notifier-id"],
  "triggerAfterNPositiveResults": 2,
  "triggerFromNRuns": 3,
  "disabled": false
}

MatchEvent :

{
  "name": "Error Event Match",
  "type": "MatchEvent",
  "aplQuery": "['logs'] | where level == 'error'",
  "rangeMinutes": 5,
  "intervalMinutes": 5,
  "notifierIds": ["notifier-id"],
  "disabled": false
}

AnomalyDetection :

{
  "name": "CPU Anomaly",
  "type": "AnomalyDetection",
  "aplQuery": "['metrics'] | summarize avg(cpu_usage)",
  "columnName": "cpu_usage",
  "operator": "AboveOrBelow",
  "rangeMinutes": 5,
  "intervalMinutes": 5,
  "notifierIds": ["notifier-id"],
  "disabled": false
}

Exemples minimaux de notifiers valides

Email :

{
  "name": "Oncall Email",
  "properties": {
    "email": {
      "emails": ["oncall@example.com"]
    }
  }
}

Slack :

{
  "name": "Oncall Slack",
  "properties": {
    "slack": {
      "slackUrl": "https://hooks.slack.com/services/T.../B.../XXX"
    }
  }
}

Webhook personnalisé :

{
  "name": "Oncall Custom Webhook",
  "properties": {
    "customWebhook": {
      "url": "https://api.example.com/alerts",
      "body": "{\"action\":\"{{.Action}}\",\"monitorID\":\"{{.MonitorID}}\"}"
    }
  }
}

Dépannage

401 Unauthorized :

• Cause : token invalide ou expiré.
• Correction :
  • Vérifiez le token dans ~/.axiom.toml.
  • Réexécutez scripts/setup et recommencez :
    • scripts/notifier-list <deployment>

403 Forbidden :

• Cause : token manque des permissions requises.
• Correction :
  • Créez/assignez des scopes de token pour la gestion des monitors/notifiers et l'accès aux requêtes de dataset.
  • Recommencez :
    • scripts/monitor-list <deployment>

404 Not Found sur get/update/delete :

• Cause : ID de monitor/notifier incorrect ou deployment/org incorrect.
• Correction :
  • Confirmez le deployment dans .axiom.toml.
  • Listez à nouveau les objets et utilisez les IDs exacts :
    • scripts/monitor-list <deployment> --json
    • scripts/notifier-list <deployment> --json

400 Bad Request sur création/mise à jour de notifier :

• Cause : forme invalide du payload du notifier.
• Correction :
  • Utilisez un canal de notifier unique dans properties.
  • Pour email, utilisez emails (et non recipients).
  • Validez par rapport à un exemple fonctionnant et recommencez :
    • scripts/notifier-create <deployment> <json-file>

400 Bad Request sur création/mise à jour de monitor :

• Cause : schéma de monitor invalide, désaccord opérateur/type ou champs de requête invalides.
• Correction :
  • Validez les champs requis : name, type, champ de requête, planification et notifierIds.
  • Confirmez que operator correspond au type de monitor et à la logique de seuil.
  • Recommencez :
    • scripts/monitor-create <deployment> <json-file>
    • scripts/monitor-update <deployment> <id> <json-file>

Monitor créé mais ne déclenche jamais d'alerte :

• Cause : seuil trop strict, fenêtre de requête incorrecte ou pas assez d'exécutions positives.
• Correction :
  • Inspectez l'historique sur une période connue comme active :
    • scripts/monitor-history <deployment> <id> <startTime> <endTime>
  • Réduisez le seuil ou élargissez rangeMinutes.
  • Ajustez triggerAfterNPositiveResults/triggerFromNRuns.

Trop d'alertes (monitor bruyant) :

• Cause : seuil trop bas ou intervalle trop court.
• Correction :
  • Augmentez le seuil.
  • Augmentez triggerAfterNPositiveResults et/ou triggerFromNRuns.
  • Augmentez intervalMinutes ou restreignez les conditions de correspondance.

Notifier existe mais pas de livraison :

• Cause : configuration de destination invalide (URL/clé/canal/liste d'emails) ou rejet côté destination.
• Correction :
  • Récupérez le notifier et vérifiez les champs de destination :
    • scripts/notifier-get <deployment> <id>
  • Recréez/mettez à jour le notifier avec les properties corrigées :
    • scripts/notifier-update <deployment> <id> <json-file>
  • Confirmez que le monitor référence les IDs de notifier corrects.