Configurer les notifications Slack
Excubius annonce les alertes dans Slack : lorsqu'une alerte s'ouvre, lorsque sa gravité augmente et lorsqu'elle se résout. Vous choisissez les canaux par entité, et chaque entité située en dessous en hérite jusqu'à ce qu'elle définisse les siens. Ce guide explique comment connecter une application Slack une fois pour toutes, ajouter des canaux pour une entité, les tester, et comment un message est routé.
Avant de commencer
- Pour ajouter des canaux, vous avez besoin du rôle Entity admin (administrateur d'entité) sur l'entité.
- Pour créer l'application Slack, vous devez être autorisé à installer des applications dans votre espace de travail Slack.
- Pour fournir le jeton de l'application à Excubius, vous devez avoir accès au serveur :
sudosur celui-ci, ou le package d'installation.
Connecter une application Slack
Vous effectuez cette opération une seule fois par installation.
-
Accédez à
https://api.slack.com/apps, sélectionnez Create New App, choisissez From scratch, donnez-lui un nom que votre équipe reconnaît et choisissez votre espace de travail. -
Sous OAuth & Permissions, ajoutez l'étendue de jeton de bot
chat:write. Excubius n'a besoin de rien d'autre. -
Sélectionnez Install to Workspace et autorisez l'installation. Copiez le Bot User OAuth Token, qui commence par
xoxb-. -
Sur le serveur, prenez l'identité du compte de service avec
sudo -iu excubiuset définissez le jeton dans/opt/excubius/.env:SLACK_BOT_TOKEN=xoxb-…SLACK_DEFAULT_CHANNEL=#alertsSLACK_DEFAULT_CHANNELreçoit les avertissements et les alertes critiques de chaque entité qui n'a aucun canal propre à aucun niveau au-dessus d'elle. Sa valeur est#alertssi vous l'omettez. -
Redémarrez la plateforme :
export XDG_RUNTIME_DIR=/run/user/$(id -u)systemctl --user restart excubius.service
Le programme d'installation demande aussi le jeton du bot Slack et le canal par défaut ; sudo ./install.sh --reconfigure les demande à nouveau. Tant qu'aucun jeton n'est défini, Settings › Notifications indique Slack is not configured on the server et rien n'est envoyé.
Ajouter un canal pour une entité
- Dans Slack, ouvrez le canal, par exemple
#ciguapa-alerts, et invitez-y l'application, par exemple avec/invite @Monitoring. L'application ne peut publier que dans les canaux dont elle est membre. - Dans Excubius, ouvrez Settings › Notifications et choisissez l'entité dans le sélecteur, par exemple Combray SA.
- Sélectionnez Add Slack channel.
- Renseignez les champs :
- Name : pour votre équipe, par exemple Alertes Combray.
- Slack channel :
#nomen minuscules, ou l'ID du canal, par exempleC0123456789. - Minimum : la gravité la plus basse publiée, Info, Warning ou Critical. Les alertes en dessous ne sont pas publiées.
- Message language : English ou Español. L'espagnol nécessite la fonctionnalité
ui.i18n; sans elle, le champ indique que les messages sont en anglais.
- Sélectionnez Add Slack channel.
- Sélectionnez Test sur le nouveau canal.
Un message de test apparaît dans le canal Slack et Excubius affiche Test message sent. Si Slack le refuse, l'erreur en indique la raison, par exemple not_in_channel : invitez l'application dans le canal, vérifiez le nom du canal et recommencez le test.
Les alertes de Combray SA et de tout ce qui se trouve en dessous sont désormais envoyées vers ce canal. Une entité peut avoir plusieurs canaux, par exemple un pour les avertissements et un autre réservé aux alertes critiques.
Désactiver, modifier ou supprimer un canal
Sur la ligne du canal :
- Utilisez son commutateur pour le désactiver sans le supprimer, puis le réactiver plus tard. Tant que tous les canaux d'une entité sont désactivés, l'entité utilise les canaux hérités du niveau supérieur.
- Sélectionnez Edit pour modifier n'importe quel champ, puis Save.
- Sélectionnez Remove pour cesser d'y envoyer des messages. Le canal lui-même reste dans Slack.
Comment un message trouve son canal
La page affiche le résultat pour l'entité choisie sous Where alerts go : ses propres canaux, ou les canaux hérités avec l'entité dont ils proviennent, ou le canal par défaut du serveur.
| Situation | Destination de l'alerte |
|---|---|
| L'entité de l'alerte a des canaux activés | Ses propres canaux, chacun filtré par son Minimum |
| Elle n'en a aucun, mais un ancêtre en a | Les canaux de l'ancêtre le plus proche qui en possède |
| Aucune entité du chemin n'a de canal | SLACK_DEFAULT_CHANNEL, pour les avertissements et les alertes critiques |
| Aucun canal et aucun canal par défaut | Nulle part ; la page l'indique |
Chaque message indique la ressource et le chemin de son entité, la vérification, la valeur comparée au seuil et l'endroit où ce seuil est défini, la durée de la condition, l'action suggérée par le catalogue des vérifications lorsqu'il y en a une, et un lien vers l'alerte. Les messages ne nomment jamais le produit.
Ce qui garde le canal calme :
- Une alerte par condition. Les répétitions mettent à jour l'alerte et n'envoient rien.
- Période de silence. Au plus un message par condition toutes les 10 minutes, sauf si la gravité augmente. Le paramètre serveur
EXCUBIUS_NOTIFY_QUIET_MINUTESmodifie la période. - Cause racine. Lorsqu'une ressource est inaccessible, une seule alerte critique Cannot reach est envoyée et les autres alertes de la ressource attendent sa résolution.
- Mises en sourdine et fenêtres de maintenance. Rien n'est envoyé tant qu'elles durent ; ce que le canal n'a pas encore reçu est envoyé à leur fin, si cela s'applique toujours.
- Pas de désescalade. Une baisse de critique à avertissement est enregistrée dans la chronologie de l'alerte, pas envoyée. Une résolution n'est envoyée que si l'ouverture l'a été.
- Fonctionnalités désactivées. Les alertes des modules dont la fonctionnalité est désactivée ne sont jamais envoyées, pas plus que les recommandations de sécurité.
Slack ne gêne jamais la supervision : les résultats sont d'abord stockés et évalués, puis les messages partent immédiatement après, ainsi que lors d'un balayage en arrière-plan toutes les 15 secondes. Un échec de remise est enregistré dans la chronologie de l'alerte et retenté par les balayages suivants, avec trois tentatives au total.
Effectuer ces opérations avec l'API
| Tâche | Requête |
|---|---|
| Afficher les canaux d'une entité et son routage effectif | GET /api/v1/entities/{id}/channels |
| Ajouter un canal | POST /api/v1/entities/{id}/channels |
| Modifier, désactiver ou activer | PATCH /api/v1/channels/{id} avec un ou plusieurs des champs name, config, min_severity, locale, enabled |
| Supprimer | DELETE /api/v1/channels/{id} |
| Envoyer un message de test | POST /api/v1/channels/{id}/test. Répond {"ok": true}, ou {"ok": false, "error": "not_in_channel"} avec la raison donnée par Slack |
curl -s "${H[@]}" -X POST "$BASE/entities/$CIGUAPA/channels" -d '{
"kind": "slack", "name": "Ciguapa alerts", "config": {"channel": "#ciguapa-alerts"},
"min_severity": "warning", "locale": "es"
}'