Guia Configuração do External Service Incident Sentry na Elven Platform

O External Services Center da Elven Platform é a ponte que conecta você às melhores ferramentas do mercado para monitorar, gerenciar e resolver incidentes de forma simples e eficiente. Nele, é possível integrar o Sentry com a Elven Platform, permitindo que cada issue identificada pelo Sentry gere um incidente diretamente na plataforma e que a resolução da issue no Sentry resolva automaticamente o incidente correspondente. Isso possibilita monitorar e analisar suas aplicações e serviços sob a perspectiva da Gestão de Incidentes, utilizando as melhores práticas e metodologias do mercado, tudo em um único lugar.

O Sentry substituiu o antigo plugin Webhook pelo modelo de Internal Integrations. Por isso, a configuração no Sentry passou a ser feita em Settings › Integrations › Custom Integrations, e não mais na antiga integração Webhook. Para novas integrações, utilize sempre a URL Sentry V3 exibida na Elven Platform. A URL Sentry (Deprecated) permanece disponível apenas para integrações já configuradas no modelo antigo.

API Token

Para integrar a Elven Platform com o Sentry, precisamos criar um API Token. Essa chave única é indispensável para que as duas plataformas se conectem com segurança, garantindo a troca de informações confiável e autenticada. Basta acessar o Organization Settings da Elven Platform, navegar até a seção de API e gerar.

Criando um API Token

No menu superior na parte de configuração de seu usuário, clique em Organization Settings.
Na aba API, clique no botão + para criar um novo API Token.

Acessando External Service Incident Sentry

Navegue até o menu principal e clique em Services Hub.
Em External Services Monitoring, selecione o item Incident Sentry.

Criando o External Services para Incident Sentry

No formulário, comece preenchendo o campo External Service Name, que será o nome do serviço externo, e defina os Responders, ou seja, as pessoas ou equipes que receberão notificações relacionadas a este serviço. Após isso, clique em CREATE para prosseguir. Essa ação criará o registro inicial do seu serviço externo.

Em seguida, localize o API Token que você gerou anteriormente e selecione-o. A Elven Platform exibirá duas URLs: Sentry (Deprecated), mantida apenas para integrações antigas, e Sentry V3, que é a URL que utilizaremos. Copie a URL Sentry V3, pois ela será informada no Sentry no próximo passo.

Não é necessário nenhum payload para integrar a plataforma com o Sentry, apenas a URL. Se desejar classificar a severidade dos incidentes criados, acrescente &severity= ao final da URL, seguido de um dos valores abaixo. Caso o parâmetro não seja informado, o incidente será criado como not-classified.

critical
high
moderate
low
informational
not-classified

https://apis.elven.works/<orgUid>/<integrationUid>/incidents/v3/sentry?token=<API Token>&severity=high

Criando a Internal Integration no Sentry

Integrar o Sentry à Elven Platform é um processo intuitivo que permite centralizar a gestão de incidentes em um único lugar, proporcionando maior agilidade e controle. Vamos explicar como realizar essa configuração de forma clara e prática.

Tudo começa acessando o painel do Sentry. Clique em Settings, localize a seção Integrations e clique em Custom Integrations. Em seguida, clique em Create New Integration, escolha a opção Internal Integration e clique em Next.

No formulário da integração, preencha o campo Name com um nome de sua preferência, por exemplo Elven Platform. No campo Webhook URL, insira a URL Sentry V3 que foi gerada quando você configurou o External Service Sentry na Elven Platform. Essa URL é fundamental para estabelecer a conexão entre as duas plataformas. Ative a opção Alert Action: é ela que permitirá selecionar a Elven Platform como ação de um alerta do Sentry. Os demais campos podem ficar em branco.

Na seção Permissions, defina a permissão Issue & Event como Read. Na seção Webhooks, mantenha todas as opções desmarcadas. Por fim, clique em Save Changes para garantir que as alterações sejam aplicadas.

Não marque a opção Errors em Webhooks. Ela envia cada evento de erro individualmente para a Elven Platform, o que gera incidentes em excesso e que nunca são resolvidos automaticamente. A opção Issues também deve permanecer desmarcada quando a integração for usada por meio de alertas, como descrito a seguir.

Criando o alerta no Sentry

Com a integração criada, o próximo passo é definir quais issues devem ser enviadas para a Elven Platform. No menu do Sentry, acesse Monitors, clique em Alerts e, em seguida, em Create Alert. Escolha o projeto desejado e, no Alert Builder, adicione os gatilhos A new issue is created e An issue is resolved. O segundo gatilho é o que permite que o incidente seja resolvido automaticamente na Elven Platform. Em Then perform these actions, selecione Send a notification via e escolha o nome que você deu à integração. Por fim, salve o alerta.

A partir desse momento, somente as issues que atenderem às condições do alerta serão enviadas para a Elven Platform. Repita esse passo para cada projeto que deve ser monitorado. Em versões mais antigas da interface do Sentry, o mesmo caminho aparece como Alerts › Create Alert › Issues, com a ação disponível na seção Actions.

Caso prefira receber todas as issues de todos os projetos da organização, sem filtro, é possível, em vez de criar alertas, marcar a opção Issues na seção Webhooks da Internal Integration, com os eventos Created, Resolved e Unresolved. Escolha apenas um dos dois modos: habilitar ambos não duplica incidentes, mas gera processamento em dobro na plataforma.

Como a integração se comporta

Quando uma issue dispara o alerta no Sentry, um incidente é criado na Elven Platform.
Quando a issue é marcada como Resolved no Sentry, o incidente correspondente é resolvido automaticamente.
Quando a issue é reaberta no Sentry, seja manualmente ou por regressão, um novo incidente é criado.

O título e a causa do incidente são preenchidos com o título e o local do erro informados pelo Sentry.

Testando a integração

Para validar a configuração, gere um erro real em um projeto coberto pelo alerta e confirme que o incidente foi criado na Elven Platform. Em seguida, marque a issue como Resolved no Sentry e confirme que o incidente foi resolvido.

O botão Send Test Notification do alerta envia apenas um evento de teste. Ele cria um incidente na Elven Platform, mas esse incidente não será resolvido automaticamente. Esse comportamento é esperado; para validar o ciclo completo, prefira o teste com um erro real.

Assim que configurado, o serviço aparecerá no External Services Monitoring Center, classificado por status, facilitando o monitoramento de incidentes com prioridade para aqueles em estado de alarme.

Integrações antigas

Integrações configuradas anteriormente por meio do plugin Webhook do Sentry continuam funcionando pela URL Sentry (Deprecated). Recomendamos migrar para o novo modelo: crie a Internal Integration e o alerta conforme descrito neste guia, utilizando a URL Sentry V3. Não é necessário alterar nada no External Service já criado na Elven Platform.

Configurações adicionais de segurança e performance

Whitelist de IPs: A comunicação via API pode ser configurada para permitir apenas IPs autorizados. Para ativar ou modificar essa configuração, entre em contato com o suporte da Elven Platform.
Rate Limiting: O tempo padrão para limitação de requisições é 5 minutos, mas pode ser ajustado conforme a necessidade. Para alterações, entre em contato com o suporte da Elven Platform.

Essas configurações garantem maior segurança e controle sobre o tráfego de dados entre os sistemas integrados.

Glossário de Termos Técnicos

Sentry: Plataforma de monitoramento e rastreamento de erros, utilizada para identificar e gerenciar problemas em aplicações.

Issue: Agrupamento de eventos de erro semelhantes no Sentry. É a unidade que gera e resolve incidentes na Elven Platform.

API Token: Chave de autenticação gerada na Elven Platform para permitir uma comunicação segura e confiável com ferramentas externas.

Organization Settings: Seção da Elven Platform onde é possível configurar opções organizacionais, como gerar API Tokens para integrações.

External Service Name: Nome dado a um serviço externo durante sua configuração, usado para identificá-lo na Elven Platform.

Responders: Pessoas ou equipes designadas para receber notificações de incidentes gerados por um serviço externo.

Internal Integration: Modelo de integração do Sentry criado em Custom Integrations, exclusivo da sua organização, que substitui o antigo plugin Webhook.

Webhook URL: URL fornecida pela Elven Platform durante a configuração do External Service, informada na Internal Integration do Sentry para estabelecer a comunicação entre as plataformas.

Alert Action: Opção da Internal Integration que permite utilizá-la como ação de um alerta do Sentry.

Sentry V3: URL atual da integração, compatível com o modelo de Internal Integrations do Sentry.

Sentry (Deprecated): URL antiga da integração, mantida apenas para integrações criadas com o plugin Webhook.

Severity: Parâmetro opcional adicionado à URL para definir a severidade dos incidentes criados pela integração.