KEPLIN Docs

Alertas por email

O que gera um alerta, o que diz o email, quem o recebe, e como ligar os avisos e afinar os limiares.

O Radar conta o que se passa a quem abrir o ecrã. Os alertas fazem o contrário: avisam sem ninguém ter de olhar. É a diferença entre saber que uma app esteve em baixo e saber que está.

Um alerta só chega quando é preciso alguém agir, e diz o que partiu, onde, quantas vezes, a quantas pessoas e desde quando, com uma ligação para o ver no Radar.

Ligam-se e afinam-se nas Definições da plataforma, no fundo da barra lateral.

Nota

Estas definições são de quem administra a instalação. Com perfil de developer, o menu Definições não aparece.

O que gera um alerta

Situação Quando avisa
Problema novo Aparece um problema numa app publicada: um erro num ecrã, num workflow ou numa rota do servidor, uma API que falha no servidor, ou um teste que falha numa execução agendada (ver Executar e ler os resultados).
Problema que voltou Um problema dado como resolvido volta a acontecer.
Problema aberto que voltou Um problema aberto, de que ninguém tinha sido avisado, volta a acontecer.
Falha generalizada A percentagem de pedidos que falham no servidor passa o limiar, com pelo menos 5 falhas e o mínimo de pedidos.
Scripts falhados As execuções falhadas de scripts passam o limiar.
Fila do índice e Disco A fila do índice atrasa-se ou o disco fica com pouco espaço livre.
Antivírus O antivírus recusa um ficheiro enviado, ou põe em quarentena um ficheiro já guardado (ver Antivírus).
Segredo de um fornecedor a expirar O segredo de um fornecedor Microsoft Entra ID expira dentro de 30 dias, ou já expirou (ver Entrar com fornecedores de autenticação).

Os problemas seguem o estado que têm no Radar (ver Investigar um problema):

  • Enquanto um problema estiver aberto, não chegam mais emails sobre ele.
  • Resolver um problema fecha o alerta sem email: quem o resolveu já sabe. Se o problema voltar a acontecer, chega um email novo a dizer que voltou.
  • Ignorar um problema cala-o: nunca gera alertas.
  • O que acontece no studio, enquanto alguém constrói ou testa a app, não avisa ninguém.

Para a falha generalizada, só contam as falhas do servidor (estado 500 ou acima). As recusas de permissão, os pedidos cancelados por quem os fez e os erros de validação do que alguém escreveu não contam. Quando uma app não tem tráfego que chegue para decidir, o alerta fica como estava: não fecha só porque as pessoas pararam de usar a app.

O que diz um email

Cada pessoa recebe um email com os alertas que lhe dizem respeito, na língua com que usa a plataforma. Num problema, o email diz:

  • O nome da app e a mensagem do erro, no assunto.
  • Onde: a API, o ecrã, o workflow ou a rota do servidor.
  • Quantas ocorrências houve na janela, e quantas no total.
  • Quantos utilizadores foram afectados.
  • Quando o problema foi visto pela primeira vez e, num problema que voltou, quando tinha sido dado como resolvido.
  • Abrir no Radar: a ligação que abre o problema no Radar da app.

Os alertas de falha generalizada e de scripts dizem que APIs ou scripts falharam, quantas vezes, e a última mensagem de erro de cada um.

Ligar os avisos

  1. Abre Definições na barra lateral.
  2. Escolhe Alarmes, no grupo Avisos.
  3. Liga Avisos por email. A ajuda diz o que está em jogo: "Avisa quando aparece um problema novo numa app, quando um problema resolvido volta a acontecer e quando algo passa dos limites em baixo. Sem isto, só sabes quando abrires o ecrã."
  4. Carrega em Gravar, no cabeçalho. A confirmação diz "Definições guardadas."

A secção Alarmes, com o interruptor Avisos por email
A secção Alarmes, com o interruptor Avisos por email

A secção Processos, no grupo Plataforma, tem outros três interruptores que valem a pena conhecer, porque metade dos "alertas que não chegam" vem de um deles estar desligado:

Interruptor O que faz
Agendador Corre os agendamentos, os relatórios agendados e os temporizadores dos workflows.
Índice de observabilidade Leva o que as apps registam para o índice central e aplica os prazos de retenção de cada app. Desligado, os ecrãs mostram dados velhos.
Notificações em tempo real Servidor de tempo real das notificações. Sem ele, as notificações entregam-se na próxima visita.

Para onde vão os avisos

A secção Email, no grupo Avisos, tem o servidor de saída e os destinatários: "O servidor por onde saem os avisos da plataforma. É distinto do email de cada app."

A secção Email, com o servidor de saída e os destinatários
A secção Email, com o servidor de saída e os destinatários

Campo O que é
Servidor O endereço do servidor de email de saída.
Porta A porta dele.
Segurança SSL/TLS (porta 465), STARTTLS se o servidor oferecer (porta 587) ou Nenhuma (porta 25).
Utilizador A conta de autenticação no servidor.
Palavra-passe "Fica cifrada e nunca volta a este ecrã. Deixar em branco mantém a que lá está."
Remetente O endereço de quem envia. É obrigatório.
Destinatários Quem recebe todos os avisos, em vez da escolha automática.

Com os Destinatários em branco, a plataforma escolhe quem avisa:

  • Os alertas de uma app vão para as pessoas atribuídas a essa app.
  • Os alertas de uma app sem ninguém atribuído, e os da plataforma (a fila do índice e o disco), vão para os administradores activos.

Dica

Deixa os Destinatários em branco. Cada app avisa quem trabalha nela, e a lista actualiza-se sozinha quando alguém entra ou sai da equipa. Uma lista escrita à mão recebe tudo de todas as apps e fica desactualizada no dia em que alguém muda de emprego.

O estado da palavra-passe aparece por baixo do campo: Definida — escreve para trocar ou Por definir.

A partir de quando avisar

Os Limiares estão na secção Alarmes, por baixo do interruptor: "Os problemas novos avisam sempre. Os valores em baixo decidem quando uma falha generalizada, os scripts, a fila do índice ou o disco enviam um email."

Os limiares da secção Alarmes, com a janela
Os limiares da secção Alarmes, com a janela

Limiar O que mede Nota
Falhas do servidor nas APIs (%) "Percentagem de pedidos que falham no servidor (5xx), por app, com pelo menos 5 falhas na janela." Conta-se app a app, não na soma de todas.
Pedidos mínimos Quantos pedidos são precisos para a percentagem contar "Abaixo disto a percentagem não diz nada: 1 erro em 3 são 33%."
Scripts falhados Quantas execuções de scripts podem falhar antes de avisar
Atraso da fila (s) Quanto pode a fila do índice atrasar-se "Enquanto a fila estiver atrasada, os ecrãs mostram dados velhos."
Disco livre (%) Abaixo de que percentagem de disco livre se avisa
Janela (min) O período em que tudo isto é contado "Período em que os números acima são contados."

Os Pedidos mínimos evitam que uma app com pouco tráfego dispare alertas de falha generalizada: com três pedidos e uma falha, a percentagem é 33% e não quer dizer nada. Cada falha do servidor já gera o seu próprio alerta de problema; a percentagem serve para o dia em que muitas coisas falham ao mesmo tempo.

Como escolher os valores

Não há números universais, mas há um método que funciona:

  1. Deixa a plataforma correr uma semana com os valores de origem.
  2. Abre Observabilidade → Visão geral com o período em 7d e olha para a Taxa de erro e a Resposta (p95) reais.
  3. Põe o limiar de Falhas do servidor nas APIs (%) um pouco acima do que é normal nessa instalação. O objectivo é apanhar o anormal, não confirmar o normal.
  4. Ajusta os Pedidos mínimos ao tráfego da app mais calma.

Atenção

Um limiar demasiado apertado é pior do que nenhum. Alertas que disparam todos os dias deixam de ser lidos ao fim de uma semana, e o importante, quando chegar, chega no meio dos outros.

Confirmar que os alertas estão mesmo a funcionar

A secção Estado da Observabilidade tem, no topo, os alertas abertos e uma frase que diz a verdade sobre os alertas nesta instalação. É o sítio para confirmar depois de mexer nas definições.

O aviso do estado dos alertas, no topo da secção Estado da Observabilidade
O aviso do estado dos alertas, no topo da secção Estado da Observabilidade

São três frases possíveis:

O que lá está O que significa
"Alertas ligados: avisa quem trabalha em cada app quando aparece um problema novo e quando um problema resolvido volta a acontecer, e também quando mais de 5% dos pedidos falham no servidor, a partir de 20 pedidos." Tudo a funcionar, com os teus limiares à vista.
"Os alertas estão desligados. Ninguém é avisado quando algo corre mal — esta página só conta o que se passa a quem a abrir." Falta ligar Avisos por email.
"Alertas ligados, mas sem envio de email: … Os alarmes são registados e ninguém é avisado." O aviso dispara, mas não sai: falta configurar o servidor de email.

A terceira é a mais traiçoeira, porque tudo parece configurado. Se a vires, volta à secção Email e completa o que falta.

Sessões e limites

Ainda nas Definições, a secção Limites, no grupo Plataforma, tem dois valores que não são alertas mas costumam ser procurados ao mesmo tempo:

  • Duração da sessão (h): "Uma sessão activa renova-se sozinha; isto é o tempo de inactividade que a expira."
  • Ficheiro máximo (MB): o tamanho máximo de um ficheiro carregado.

Porque não vejo…?

  • …alertas a chegar, com tudo ligado? Confirma o painel Estado: se disser "sem envio de email", falta o servidor de saída. Se disser "desligados", falta gravar.
  • …os alertas de uma app? Os alertas de uma app vão para quem está atribuído a ela. Confirma em Utilizadores que estás atribuído à app.
  • …outro email do mesmo problema? Um problema aberto só avisa uma vez. Volta a avisar se for dado como resolvido e voltar a acontecer.
  • …o alerta de um erro que vi no studio? O que acontece no studio, a quem está a construir a app, não avisa ninguém. Só a app publicada gera alertas.
  • …a secção Alarmes? Estás nas definições de uma app, não nas da plataforma. As da plataforma abrem-se pelo menu Definições da barra lateral.
  • …os meus limiares a valer? Sem Gravar, no cabeçalho, nada é guardado. A confirmação é "Definições guardadas."