Configurar notificações do Slack
O Excubius anuncia os alertas no Slack: quando um alerta é aberto, quando a severidade dele aumenta e quando ele é resolvido. Você escolhe os canais por entidade, e cada entidade abaixo os herda até definir os próprios. Este guia mostra como conectar um aplicativo do Slack uma única vez, adicionar canais para uma entidade e testá-los, e como uma mensagem é roteada.
Antes de começar
- Para adicionar canais, você precisa da função Entity admin (administrador de entidade) na entidade.
- Para criar o aplicativo do Slack, você precisa de permissão para instalar aplicativos no seu workspace do Slack.
- Para entregar o token do aplicativo ao Excubius, você precisa de acesso ao servidor:
sudonele ou o pacote do instalador.
Conectar um aplicativo do Slack
Você faz isso uma vez por instalação.
-
Acesse
https://api.slack.com/apps, selecione Create New App, escolha From scratch, dê a ele um nome que a sua equipe reconheça e escolha o seu workspace. -
Em OAuth & Permissions, adicione o escopo de token de bot
chat:write. O Excubius não precisa de mais nada. -
Selecione Install to Workspace e permita a instalação. Copie o Bot User OAuth Token, que começa com
xoxb-. -
No servidor, assuma a conta de serviço com
sudo -iu excubiuse defina o token em/opt/excubius/.env:SLACK_BOT_TOKEN=xoxb-…SLACK_DEFAULT_CHANNEL=#alertsSLACK_DEFAULT_CHANNELrecebe os avisos e os alertas críticos de todas as entidades que não têm um canal próprio em nenhum nível acima delas. Ele é#alertsquando você o omite. -
Reinicie a plataforma:
export XDG_RUNTIME_DIR=/run/user/$(id -u)systemctl --user restart excubius.service
O instalador também pede o token de bot do Slack e o canal padrão; sudo ./install.sh --reconfigure pede novamente. Enquanto nenhum token estiver definido, Settings › Notifications exibe Slack is not configured on the server e nada é enviado.
Adicionar um canal para uma entidade
- No Slack, abra o canal, por exemplo
#ciguapa-alerts, e convide o aplicativo para ele, por exemplo com/invite @Monitoring. O aplicativo só pode publicar nos canais dos quais faz parte. - No Excubius, abra Settings › Notifications e escolha a entidade no seletor, por exemplo Veredas Ltda..
- Selecione Add Slack channel.
- Preencha os campos:
- Name: para a sua equipe, por exemplo Alertas Veredas.
- Slack channel:
#nameem letras minúsculas ou o ID do canal, comoC0123456789. - Minimum: a menor severidade publicada, Info, Warning ou Critical. Os alertas abaixo dela não são publicados.
- Message language: English ou Español. O espanhol exige a opção de recurso
ui.i18n; sem ela, o campo informa que as mensagens estão em inglês.
- Selecione Add Slack channel.
- Selecione Test no novo canal.
Uma mensagem de teste aparece no canal do Slack e o Excubius exibe Test message sent. Se o Slack a recusar, o erro indica o motivo, por exemplo not_in_channel: convide o aplicativo para o canal, verifique o nome do canal e teste novamente.
Os alertas da Veredas Ltda. e de tudo o que está abaixo dela passam a ir para esse canal. Uma entidade pode ter vários canais, por exemplo um para avisos e outro apenas para alertas críticos.
Desativar, alterar ou remover um canal
Na linha do canal:
- Use a chave dele para desativá-lo sem removê-lo e ativá-lo novamente mais tarde. Enquanto todos os canais de uma entidade estiverem desativados, a entidade usa os canais herdados de cima.
- Selecione Edit para alterar qualquer campo e, em seguida, Save.
- Selecione Remove para parar de enviar para ele. O canal em si continua no Slack.
Como uma mensagem encontra o canal
A página mostra o resultado para a entidade escolhida em Where alerts go: os canais próprios dela, os canais herdados com a entidade de onde vêm ou o canal padrão do servidor.
| Situação | Para onde o alerta vai |
|---|---|
| A entidade do alerta tem canais habilitados | Para os canais próprios dela, cada um filtrado pelo respectivo Minimum |
| Ela não tem nenhum, mas um ancestral tem | Para os canais do ancestral mais próximo que tenha algum |
| Nenhuma entidade no caminho tem canal | Para SLACK_DEFAULT_CHANNEL, no caso de avisos e alertas críticos |
| Nenhum canal e nenhum canal padrão | Para lugar nenhum; a página informa isso |
Cada mensagem contém o recurso e o caminho da entidade dele, a verificação, o valor em relação ao limite e onde esse limite está definido, há quanto tempo a condição persiste, a ação sugerida do catálogo de verificações quando houver uma e um link para o alerta. As mensagens nunca citam o nome do produto.
O que mantém o canal tranquilo:
- Um alerta por condição. As repetições atualizam o alerta e não enviam nada.
- Período de silêncio. No máximo uma mensagem por condição a cada 10 minutos, a menos que a severidade aumente. A configuração de servidor
EXCUBIUS_NOTIFY_QUIET_MINUTESaltera o período. - Causa raiz. Quando um recurso não pode ser alcançado, um único alerta crítico Cannot reach é enviado, e os outros alertas do recurso aguardam até que ele seja resolvido.
- Silenciamentos e janelas de manutenção. Nada é enviado enquanto eles duram; o que o canal ainda não recebeu é enviado quando eles terminam, se ainda se aplicar.
- Sem redução de severidade. Uma queda de crítico para aviso é registrada na linha do tempo do alerta, não enviada. Uma resolução só é enviada quando a abertura também foi.
- Opções de recurso desativadas. Os alertas de módulos cuja opção de recurso está desativada nunca são enviados, assim como as recomendações de segurança.
O Slack nunca atrapalha o monitoramento: os resultados são armazenados e avaliados primeiro, e as mensagens são enviadas logo depois e por uma varredura em segundo plano a cada 15 segundos. Uma entrega com falha é registrada na linha do tempo do alerta e repetida nas próximas varreduras, em um total de três tentativas.
Fazer isso com a API
| Tarefa | Solicitação |
|---|---|
| Ver os canais de uma entidade e o roteamento efetivo dela | GET /api/v1/entities/{id}/channels |
| Adicionar um canal | POST /api/v1/entities/{id}/channels |
| Alterar, desativar ou ativar | PATCH /api/v1/channels/{id} com qualquer um de name, config, min_severity, locale, enabled |
| Remover | DELETE /api/v1/channels/{id} |
| Enviar uma mensagem de teste | POST /api/v1/channels/{id}/test. Responde {"ok": true} ou {"ok": false, "error": "not_in_channel"} com o motivo do 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"
}'