Alertas do Sentry por ligação para erros críticos

Sumário

• Por que o Sentry sozinho não faz seu telefone tocar
• O que você precisa
• Passo 1 — Crie um canal que toca
• Passo 2 — Crie uma integração interna no Sentry
• Passo 3 — Adicione a integração como ação da regra
• Passo 4 — Saiba o que chega de verdade
• Passo 5 — Estreite até o que merece uma ligação
• Passo 6 — Uma porta mais silenciosa para os avisos
• Tocar só fora do horário de trabalho
• As duas armadilhas
• Tamanho do payload, tempestades e truncamento
• Compartilhando com o time
• O que esta configuração não oferece
• Solução de problemas
• Perguntas frequentes
• O Sentry consegue fazer uma ligação nativamente?
• Um alerta do Sentry atravessa o Não Perturbe?
• Preciso de plano pago do Sentry para usar webhooks?
• Por que minha variável de template está vazia?
• Como alertar apenas sobre um ambiente?
• Duas pessoas podem ser chamadas pelo mesmo erro?
• Devo filtrar no Sentry ou no Echobell?
• Fechando
• Artigos relacionados

O Sentry não consegue te ligar. Ele manda e-mail, posta no Slack ou entrega o alerta ao PagerDuty — mas não existe uma ação de voz embutida. O jeito de ter uma sem comprar uma plataforma de incidentes é mandar o alerta do Sentry para um webhook que toca: crie uma integração interna, aponte para um canal de ligação do Echobell e coloque um filtro na frente, para que só passem os erros que realmente quebram a produção.

Este guia cobre o caminho inteiro: a integração, a regra de alerta, o payload que o Sentry manda de verdade, os templates que o leem e as duas armadilhas que fazem as pessoas desistirem.

Por que o Sentry sozinho não faz seu telefone tocar

As ações dos alertas de issue do Sentry cobrem notificações (e-mail, Slack, Discord, Microsoft Teams), criação de tickets (Jira, GitHub, Azure DevOps) e repasse para um produto de plantão (PagerDuty, Opsgenie). Todas terminam numa tela que você precisa estar olhando, ou num assento pago de outra plataforma.

Às 14h, tudo bem. Às 3h da manhã, uma mensagem no Slack é indistinguível do silêncio, e uma notificação push perde para o Não Perturbe. Para aquele conjunto pequeno de erros em que duas horas de atraso custam dinheiro de verdade — checkout devolvendo 500, autenticação recusando todo mundo, um worker descartando jobs em silêncio — você quer um aparelho que toque.

O webhook é a emenda. O Sentry consegue chamar qualquer endpoint HTTPS como ação de uma regra de alerta; o Echobell transforma essa requisição HTTP num alerta em formato de ligação que atravessa o modo Foco do iOS.

O que você precisa

• Uma organização no Sentry onde você consiga chegar em Settings → Developer Settings (owner ou manager)
• Echobell instalado (App Store / Google Play)
• Cinco minutos

Nada do seu lado precisa ser alcançável pela internet. Quem faz a requisição de saída é o Sentry; você só recebe.

Passo 1 — Crie um canal que toca

No Echobell, crie um canal e defina o tipo de notificação como Ligação. É todo o ponto do exercício: um canal de ligação se comporta como uma chamada recebida em vez de um push, então atravessa o modo Foco e o Não Perturbe.

Dê a ele templates que façam sentido às 3 da manhã. O payload do Sentry é bem aninhado, então os caminhos das variáveis ficam mais longos que o normal:

Título: {{data.event.level}}: {{data.event.metadata.type}}
Corpo: {{data.event.title}} — {{data.event.culprit}}

Configure o template de link nas configurações avançadas para que tocar na notificação abra a issue:

{{data.event.web_url}}

Copie a URL do webhook na tela de detalhes do canal. Ela tem esta cara:

https://hook.echobell.one/t/<channel-token>

Passo 2 — Crie uma integração interna no Sentry

O Sentry só oferece um webhook como ação de regra por meio de uma integração, então você precisa criar uma. É um formulário, não um serviço — você não escreve código nenhum.

1. Vá em Settings → Developer Settings → Custom Integrations
2. Create New Integration → Internal Integration
3. Name: Echobell (é o rótulo que você vai escolher na regra)
4. Webhook URL: a URL do canal do passo 1
5. Ligue a chave Alert Rule Action
6. Permissions: Issue & Event → Read já basta
7. Em Webhooks, deixe todas as caixas desmarcadas — veja a armadilha abaixo
8. Salve

Uma integração interna fica restrita à sua organização e se instala sozinha. O token que ela gera nunca é necessário nesta configuração.

Passo 3 — Adicione a integração como ação da regra

Vá em Alerts → Create Alert → Issue Alert, ou edite uma regra existente.

Em Then perform these actions, adicione Send a notification via an integration e escolha Echobell.

Defina o Action interval — o limitador de "se este alerta disparou mais de uma vez" — para pelo menos 30 minutes. O padrão envia a cada disparo, e um erro que dispara 400 vezes por minuto vai discar seu número até você desligar tudo.

Salve e rode o teste da regra para ver um payload real chegando antes de confiar nele.

Passo 4 — Saiba o que chega de verdade

É aqui que a maioria das configurações quebra, porque o payload não tem o formato que você imagina. O Sentry embrulha tudo:

{
  "action": "triggered",
  "actor": { "id": "sentry", "name": "Sentry", "type": "application" },
  "data": {
    "event": {
      "event_id": "e4874d664c3540c1a32eab185f12c5ab",
      "level": "error",
      "title": "ReferenceError: heck is not defined",
      "culprit": "?(<anonymous>)",
      "platform": "javascript",
      "project": 1,
      "release": null,
      "metadata": { "type": "ReferenceError", "value": "heck is not defined" },
      "tags": [["level", "error"], ["browser", "Chrome 75.0.3770"]],
      "issue_id": "1117540176",
      "issue_url": "https://sentry.io/api/0/issues/1117540176/",
      "web_url": "https://sentry.io/organizations/test-org/issues/1117540176/events/e4874.../"
    },
    "triggered_rule": "Very Important Alert!"
  },
  "installation": { "uuid": "a8e5d2..." }
}

Quatro coisas para saber antes de escrever qualquer template:

• Tudo o que é útil está sob data.event. {{title}} não renderiza nada; {{data.event.title}} renderiza o erro.
• data.event.project é um ID numérico, não um slug. Se quiser um nome de projeto legível na notificação, escreva-o como texto no template do título e use um canal por projeto.
• Não existe campo environment. O ambiente chega dentro de data.event.tags como par ["environment", "production"], e a posição dele no array não é estável — então não acesse por índice. Filtre o ambiente na regra do Sentry (passo 5).
• data.triggered_rule é o nome da regra. Útil no corpo quando um canal atende a várias regras.

O cabeçalho Sentry-Hook-Resource vale event_alert para alertas de issue. Você pode exigi-lo numa condição do canal para que nada mais consiga fazê-lo tocar:

header["sentry-hook-resource"] == "event_alert"

Passo 5 — Estreite até o que merece uma ligação

Um canal de ligação que toca a cada issue nova é pior do que canal nenhum: em uma semana você o terá silenciado, e aí ele não vai tocar naquela que importava. Filtre em dois lugares.

No Sentry, com as conditions e filters da regra:

No Echobell, use uma condição de canal como rede de segurança para o que o Sentry não expressa, ou para mudanças que você não consegue subir hoje:

data.event.level == "fatal" || data.event.level == "error"

Filtrar severidade na regra do Sentry costuma ser melhor, porque é lá que também vive o controle de frequência. Fazer no Echobell é melhor quando você quer dois níveis de urgência a partir de uma única regra.

Passo 6 — Uma porta mais silenciosa para os avisos

O sentido dos níveis é que a ligação preserve o significado dela. Crie um segundo canal Echobell do tipo Urgente (Time Sensitive), adicione uma segunda regra do Sentry com um limiar mais baixo e aponte-a para uma segunda integração interna (uma integração guarda uma única URL de webhook, então um segundo canal exige uma segunda integração).

Uma configuração que sobrevive a uma semana real fica mais ou menos assim:

Tocar só fora do horário de trabalho

Durante o dia você já está olhando o Sentry. O Echobell expõe variáveis de hora do sistema em UTC para as condições, então um canal pode se comportar de forma diferente por horário sem precisar de uma segunda regra:

data.event.level == "fatal" && (hour >= 17 || hour < 9)

Acrescente uma checagem de dia se o seu fim de semana for realmente livre:

data.event.level == "fatal" && (hour >= 17 || hour < 9 || dayOfWeek == 0 || dayOfWeek == 6)

Tudo isso é UTC, então converta do seu fuso antes de cravar os números. A referência de condições tem a lista completa de variáveis.

As duas armadilhas

Armadilha 1: marcar as caixas de Webhooks. Uma integração interna tem dois caminhos de webhook independentes. A chave Alert Rule Action faz a integração aparecer como opção nas regras de alerta — é essa que você quer. As caixas de Webhooks (issue, error, comment) inscrevem você em todos os eventos daquele recurso: toda issue criada, resolvida, atribuída, arquivada ou ignorada, em toda a organização. Marque issue e seu telefone vai tocar quando um colega resolver alguma coisa. Deixe todas desmarcadas e só as suas regras disparam o webhook.

Armadilha 2: usar o plugin antigo de Webhooks. O antigo plugin por projeto Legacy Integrations → WebHooks ainda existe e ainda funciona, e parece um atalho porque dá para colar uma URL sem criar integração. O payload dele tem outro formato, mais plano, as requisições não são assinadas, e o próprio Sentry direciona as configurações novas para outro lado. Se você usá-lo, seus templates vão precisar de caminhos de variáveis diferentes dos acima. Use a integração interna.

Tamanho do payload, tempestades e truncamento

Três limites que vale conhecer antes de algo dar errado em escala:

• 1 MiB de corpo. O Echobell rejeita corpos de disparo acima de 1 MiB com HTTP 413. Um payload do Sentry carrega o stack trace completo e o contexto da requisição, o que normalmente fica na casa das dezenas de kilobytes — mas um evento com corpo de requisição grande pode chegar perto. Não existe um max_alerts no lado do Sentry, então a mitigação é limpar corpos grandes no beforeSend do seu SDK, coisa que você já quer fazer por privacidade.
• 120 requisições por minuto por token. Acima disso o gatilho responde 429 com RATE_LIMIT_EXCEEDED e um Retry-After. Quem te mantém abaixo é o action interval do Sentry; 30 minutes sobra.
• 1500 bytes de corpo da notificação. O que passar disso é truncado antes de chegar ao aparelho. data.event.title mais culprit cabe folgado; despejar data.event.exception não cabe — e de todo modo é ilegível numa tela bloqueada. Deixe o detalhe atrás do template de link.

Compartilhando com o time

Várias pessoas podem assinar um canal do Echobell, e cada assinante escolhe o próprio tipo de notificação. A mesma regra do Sentry pode, assim, fazer tocar o telefone de quem está de plantão e chegar como push comum para o resto — sem cobrança por assento, sem configuração de escala.

O que ele não é: uma política de escalonamento. Não existe "se ninguém confirmar em cinco minutos, ligue para o próximo". Se você precisa disso, precisa de uma plataforma de plantão de verdade; o Echobell cobre a camada de entrega embaixo dela.

O que esta configuração não oferece

Melhor dizer com todas as letras:

• Sem confirmação. Atender a ligação não avisa nada ao Sentry e não para os telefones dos outros assinantes.
• Sem escala nem escalonamento. Ou todos os inscritos recebem, ou ninguém.
• Sem deduplicação além da do Sentry. Agrupamento e limitação acontecem na regra; o Echobell entrega o que chega.
• Sem sincronização bidirecional. Resolver a issue no Sentry não limpa nada no seu telefone.

Se isso for impeditivo, esta é a ferramenta errada. Se o que você precisa mesmo é "me acorde quando o checkout quebrar", é mais ou menos a forma confiável mais barata de conseguir.

Solução de problemas

A regra dispara mas nada chega. Confira se Alert Rule Action está ligado na integração. Se estiver desligado, a integração nem aparece na lista de ações — e uma regra salva antes de você ligar mantém a ação obsoleta.

Chega notificação, mas em branco. Seu template está lendo chaves de primeiro nível. O Sentry aninha tudo sob data.event.

Toca por coisas inesperadas. Verifique as caixas de Webhooks da integração (armadilha 1) e depois se o ambiente da regra ficou em "All Environments".

Toca várias vezes pelo mesmo erro. Aumente o action interval da regra. A retentativa do Echobell é outra coisa: Repetir ligação com falha, nas configurações do app, rediscar uma ligação perdida.

Nunca chega nada, nem o teste. Dispare o canal com curl primeiro, para descartar o lado do Echobell:

curl -X POST https://hook.echobell.one/t/<channel-token> \
  -H 'Content-Type: application/json' \
  -d '{"data":{"event":{"level":"fatal","title":"Test error","culprit":"manual test","metadata":{"type":"TestError"}}}}'

Se isso toca e o Sentry não, o problema está na integração, não no canal.

Perguntas frequentes

O Sentry consegue fazer uma ligação nativamente?

Não. As ações de alerta do Sentry são notificações, criação de tickets e integrações com produtos de plantão. Uma chamada de voz exige um serviço externo: ou uma plataforma como o PagerDuty, ou um receptor de webhook que toca, como o Echobell.

Um alerta do Sentry atravessa o Não Perturbe?

Só se chegar como alerta em formato de ligação. Um canal do Echobell do tipo ligação se comporta como uma chamada recebida, e isso o modo Foco e o Não Perturbe do iOS deixam passar. Um push comum de qualquer app, não.

Preciso de plano pago do Sentry para usar webhooks?

Integrações internas e ações de regra estão disponíveis a partir do plano Developer do Sentry. O webhook em si não custa nada a mais.

Por que minha variável de template está vazia?

Quase sempre porque o caminho é curto demais. O payload do alerta aninha o evento sob data.event, então é {{data.event.title}}, não {{title}}. Dispare o canal uma vez e veja o corpo da requisição registrado no app para conferir o formato exato.

Como alertar apenas sobre um ambiente?

Preencha o campo Environment na regra de alerta do Sentry. Não tente ler de data.event.tags — é um array de pares [chave, valor] sem ordem garantida.

Duas pessoas podem ser chamadas pelo mesmo erro?

Podem. Compartilhe o canal e deixe cada pessoa assinar com o tipo de notificação que preferir. Como não há confirmação, todos que escolheram "ligação" recebem a chamada.

Devo filtrar no Sentry ou no Echobell?

No Sentry quando der — a regra também é onde vivem o controle de frequência e o recorte por ambiente. No Echobell quando você quer dois níveis de urgência a partir de uma regra, quando precisa de uma janela de horário, ou quando a regra não pode ser mexida hoje.

Fechando

A configuração são quatro coisas: um canal de ligação, uma integração interna com Alert Rule Action ligado e as caixas de Webhooks desmarcadas, uma regra de alerta estreita o bastante para merecer uma ligação, e templates que leem data.event. Todo o resto desta página é sobre mantê-la estreita o suficiente para que, daqui a um mês, aquele toque ainda signifique alguma coisa.

Baixe o Echobell para iPhone ou pegue no Google Play, e mande o curl acima antes de confiar algo realmente importante a esse caminho.

Artigos relacionados

• Referência de condições de canal
• Guia de integração com webhooks
• Guia do desenvolvedor para a fadiga de alertas
• Alertas por ligação com Prometheus Alertmanager
• Furando o modo Foco do iOS para alertas críticos