Configurar las notificaciones de Slack
Excubius anuncia las alertas en Slack: cuando una se abre, cuando su severidad sube y cuando se resuelve. Eliges los canales por entidad, y cada entidad que está debajo los hereda hasta que configura los suyos. Esta guía muestra cómo conectar una aplicación de Slack una sola vez, agregar canales para una entidad, probarlos y cómo se enruta un mensaje.
Antes de empezar
- Para agregar canales, necesitas el rol Administrador de entidad en la entidad.
- Para crear la aplicación de Slack, necesitas permiso para instalar aplicaciones en tu espacio de trabajo de Slack.
- Para entregar el token de la aplicación a Excubius, necesitas acceso al servidor:
sudoen él, o el paquete del instalador.
Conectar una aplicación de Slack
Esto se hace una vez por instalación.
-
Ve a
https://api.slack.com/apps, selecciona Create New App, elige From scratch, ponle un nombre que tu equipo reconozca y elige tu espacio de trabajo. -
En OAuth & Permissions, agrega el ámbito de token de bot
chat:write. Excubius no necesita nada más. -
Selecciona Install to Workspace y permítelo. Copia el Bot User OAuth Token, que empieza por
xoxb-. -
En el servidor, cambia a la cuenta de servicio con
sudo -iu excubiusy configura el token en/opt/excubius/.env:SLACK_BOT_TOKEN=xoxb-…SLACK_DEFAULT_CHANNEL=#alertsSLACK_DEFAULT_CHANNELrecibe las advertencias y las alertas críticas de todas las entidades que no tienen un canal propio en ningún nivel por encima. Es#alertssi no lo indicas. -
Reinicia la plataforma:
export XDG_RUNTIME_DIR=/run/user/$(id -u)systemctl --user restart excubius.service
El instalador también pide el token del bot de Slack y el canal predeterminado; sudo ./install.sh --reconfigure los vuelve a pedir. Hasta que se configura un token, Configuración › Notificaciones indica Slack no está configurado en el servidor y no se envía nada.
Agregar un canal para una entidad
- En Slack, abre el canal, por ejemplo
#ciguapa-alerts, e invita a la aplicación, por ejemplo con/invite @Monitoring. La aplicación solo puede publicar en los canales de los que forma parte. - En Excubius, abre Configuración › Notificaciones y elige la entidad en el selector, por ejemplo Ciguapa Inc..
- Selecciona Agregar canal de Slack.
- Completa los campos:
- Nombre: para tu equipo, por ejemplo Alertas de Ciguapa.
- Canal de Slack:
#nameen minúsculas, o el ID del canal, comoC0123456789. - Mínimo: la severidad más baja que se publica, Información, Advertencia o Crítico. Las alertas por debajo de ella no se publican.
- Idioma de los mensajes: English o Español. El español necesita la función
ui.i18n; sin ella, el campo indica que los mensajes están en inglés.
- Selecciona Agregar canal de Slack.
- Selecciona Probar en el canal nuevo.
Aparece un mensaje de prueba en el canal de Slack y Excubius muestra Mensaje de prueba enviado. Si Slack lo rechaza, el error indica el motivo, por ejemplo not_in_channel: invita a la aplicación al canal, revisa el nombre del canal y vuelve a probar.
Las alertas de Ciguapa Inc. y de todo lo que está debajo van ahora a ese canal. Una entidad puede tener varios canales, por ejemplo uno para las advertencias y otro solo para las alertas críticas.
Desactivar, cambiar o quitar un canal
En la fila del canal:
- Usa su interruptor para desactivarlo sin quitarlo, y vuelve a activarlo más adelante. Mientras todos los canales de una entidad estén desactivados, la entidad usa los canales heredados de arriba.
- Selecciona Editar para cambiar cualquier campo y luego Guardar.
- Selecciona Quitar para dejar de enviar a él. El canal en sí permanece en Slack.
Cómo encuentra un mensaje su canal
La página muestra el resultado para la entidad elegida en A dónde van las alertas: sus propios canales, los heredados con la entidad de la que vienen, o el canal predeterminado del servidor.
| Situación | Adónde va la alerta |
|---|---|
| La entidad de la alerta tiene canales activados | A sus propios canales, cada uno filtrado por su Mínimo |
| No tiene ninguno, pero un ancestro sí | A los canales del ancestro más cercano que tenga alguno |
| Ninguna entidad del camino tiene un canal | A SLACK_DEFAULT_CHANNEL, para advertencias y alertas críticas |
| Ningún canal y ningún canal predeterminado | A ningún sitio; la página lo indica |
Cada mensaje incluye el recurso y su ruta de entidades, la comprobación, el valor frente al umbral y dónde se establece ese umbral, cuánto tiempo lleva la condición, la acción sugerida del catálogo de comprobaciones cuando la hay, y un enlace a la alerta. Los mensajes nunca nombran el producto.
Lo que mantiene tranquilo el canal:
- Una alerta por condición. Las repeticiones actualizan la alerta y no envían nada.
- Periodo de silencio. Como máximo un mensaje por condición cada 10 minutos, salvo que suba la severidad. La configuración del servidor
EXCUBIUS_NOTIFY_QUIET_MINUTEScambia el periodo. - Causa raíz. Cuando no se puede llegar a un recurso, se envía una sola alerta crítica Sin conexión y las demás alertas del recurso esperan hasta que se resuelve.
- Silencios y ventanas de mantenimiento. No se envía nada mientras duran; lo que el canal todavía no ha recibido se envía cuando terminan, si sigue siendo válido.
- Sin desescaladas. Una bajada de crítica a advertencia se registra en la cronología de la alerta, no se envía. Una resolución solo se envía cuando se envió la apertura.
- Funciones desactivadas. Las alertas de los módulos cuya función está desactivada nunca se envían, ni tampoco las recomendaciones de seguridad.
Slack nunca entorpece el monitoreo: los resultados primero se guardan y se evalúan, y los mensajes salen justo después y desde un barrido en segundo plano cada 15 segundos. Una entrega fallida se registra en la cronología de la alerta y se reintenta en los siguientes barridos, tres intentos en total.
Hacerlo con la API
| Tarea | Solicitud |
|---|---|
| Ver los canales de una entidad y su enrutamiento efectivo | GET /api/v1/entities/{id}/channels |
| Agregar un canal | POST /api/v1/entities/{id}/channels |
| Cambiar, desactivar o activar | PATCH /api/v1/channels/{id} con cualquiera de name, config, min_severity, locale, enabled |
| Quitar | DELETE /api/v1/channels/{id} |
| Enviar un mensaje de prueba | POST /api/v1/channels/{id}/test. Responde {"ok": true}, o {"ok": false, "error": "not_in_channel"} con el motivo de 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"
}'