Criando Novos Alertas (Runtime Alerts)

Para configurar um novo alerta a partir do monitoramento de APIs, clique no botão + NEW DEFINITION, no canto superior direito da página Runtime Alerts.

A criação de um alerta é feita por meio de um wizard com três etapas, especificadas no restante desta página:

EVENT, para definir o que será monitorado e com que frequência;
ACTIONS, para configurar os meios utilizados para enviar a notificação; e
REVIEW, que exibe as informações cadastradas para o alerta criado.

Event

A etapa EVENT compreende a definição do que deve ser monitorado e com que frequência. Ela inclui estas seções de cadastro: OVERVIEW, EVENT DETAILS, COMPARE WITH PAST PERIOD, SILENT INTERVAL e SCHEDULE.

O cadastro padrão de alertas é feito a partir de valores absolutos que, quando ultrapassados ou não ultrapassados em um determinado período (a depender da configuração), dispararão uma notificação.

Mas também é possível incluir alertas que disparam notificações quando os valores cadastrados são atingidos em relação a um período passado. Nesse caso, os valores não são absolutos, mas indicam uma referência de comparação entre performance atual e passada. Essa comparação é configurada no campo COMPARE WITH PAST PERIOD.

Overview

A primeira seção de cadastro é a OVERVIEW, que compreende três informações iniciais a serem completadas:

Name: nome para ajudar a identificar o alerta (não precisa ser único).
Notification Type: tipo de notificação. Opções: total calls (total de chamadas), availability (disponibilidade), latency (latência) e HTTP response status (códigos de estado de respostas HTTP).
Classification: classificação, que representa o nível de criticidade. Opções: neutral (neutro), success (sucesso), warning (atenção) e critical (crítico).

A classificação não tem um significado pré-definido. O usuário pode definir a criticidade de cada ação como julgar melhor, seguindo suas regras de negócio.

Após escolher o tipo, as seções restantes de cadastro serão exibidas.

Event Details

Os campos da seção EVENT DETAILS compreendem as informações centrais do evento a ser monitorado. Aqui, você deve informar o recurso de API e a operação que quer checar e os valores de referência que farão disparar a notificação.

Para manter o monitoramento o mais focado possível, e assim conseguir visualizar os pontos de atenção, os alertas são configurados a nível de operação. Mas lembre-se que você pode criar alertas para todas as operações que necessitar (bem como para quantos recursos de uma API quiser).

Os campos formam a mensagem padrão enviada na notificação e variam de acordo com o tipo de alerta configurado:

Total Calls

Esse alerta é disparado quando uma quantidade total de chamadas em um dado período é atingida ou não atingida, a depender das configurações.

API Name: campo para inserir o nome da API que se deseja monitorar, com função autocompletar a partir das suas APIs na Plataforma da Sensedia.
Environment: ambiente em que a API escolhida está implementada.
Resource: recurso da API a ser monitorado.
Operation: operação a ser monitorada para o recurso escolhido.

returned <Operator> <Call Qty> requests over the last <Period> <Unit>: campo para configuração do número total de chamadas por período a ser considerado para o alerta. Ele é composto por:

Operator: qualifica o valor inserido com as opções "mais de" ("more than") ou "menos de" ("fewer than").

Call Qty: campo para inserir o valor de quantidade de chamadas cuja ultrapassagem (ou não ultrapassagem, vide o operador escolhido no item anterior) disparará o alerta.

Este campo tem uma variação se o usuário habilitar a comparação com um período passado na configuração do alerta. Então, ele incluirá a escolha de número total de chamadas ou variação percentual como unidade de referência para estabelecer a comparação de performance. Ver mais na seção Compare with Past Period.

Period / Unit: campos que compõem o período de tempo a ser considerado para a contabilização do valor inserido. Em Period, incluir o número e em Unit a unidade de tempo (opções: minutos e horas).

Tempo máximo que pode ser configurado: 24 horas (ou 1440 minutos).

Availability

O tipo refere-se à disponibilidade de uma dada operação a um recurso (em porcentagem).

API Name: campo para inserir o nome da API que se deseja monitorar, com função autocompletar a partir das suas APIs na Plataforma da Sensedia.
Environment: ambiente em que a API escolhida está implementada.
Resource: recurso da API a ser monitorado.
Operation: operação a ser monitorada para o recurso escolhido.
availability was <Operator> <Percentage> % over the last <Period> <Unit>: campo para configuração da porcentagem de disponibilidade por período a ser considerada para o alerta. Ele é composto por:
- Operator: qualifica o valor inserido com as opções "mais de" ("more than") ou "menos de" ("less than").
- Percentage: valor de porcentagem de disponibilidade cuja ultrapassagem (ou não ultrapassagem, vide o operador escolhido no item anterior) disparará o alerta.
- Period / Unit: campos que compõem o período de tempo a ser considerado para a contabilização do valor inserido. Em Period, incluir o número e em Unit a unidade de tempo (opções: minutos e horas).
  
  Tempo máximo que pode ser configurado: 24 horas (ou 1440 minutos).

Latency

O tipo refere-se à latência média (em milissegundos) em dado período.

API Name: campo para inserir o nome da API que se deseja monitorar, com função autocompletar a partir das suas APIs na Plataforma da Sensedia.
Environment: ambiente em que a API escolhida está implementada.
Resource: recurso da API a ser monitorado.
Operation: operação a ser monitorada para o recurso escolhido.

average latency was <Operator> <Latency> ms over the last <Period> <Unit>: campo para configuração da latência média em ms por período a ser considerada para o alerta. Ele é composto por:

Operator: qualifica o valor inserido com as opções "mais de" ("more than") ou "menos de" ("less than").

Latency: valor de latência média em ms cuja ultrapassagem (ou não ultrapassagem, vide o operador escolhido no item anterior) disparará o alerta.

Este campo tem uma variação se o usuário habilitar a comparação com um período passado na configuração do alerta. Então, ele incluirá a escolha entre um valor em ms ou variação percentual de latência para estabelecer a comparação de performance. Ver mais na seção Compare with Past Period.

Period / Unit: campos que compõem o período de tempo a ser considerado para a contabilização do valor inserido. Em Period, incluir o número e em Unit a unidade de tempo (opções: minutos e horas).

Tempo máximo que pode ser configurado: 24 horas (ou 1440 minutos).

HTTP Response Status

O tipo refere-se à quantidade retornada de um dado código de estado HTTP (em porcentagem ou número total).

API Name: campo para inserir o nome da API que se deseja monitorar, com função autocompletar a partir das suas APIs na Plataforma da Sensedia.
Environment: ambiente em que a API escolhida está implementada.
Resource: recurso da API a ser monitorado.
Operation: operação a ser monitorada para o recurso escolhido.
returned <Operator> <Quantity> <Unit> with <Response Status> over the last <Period> <Unit>: campo para configuração do número total ou porcentagem de retornos de um determinado código de estado HTTP por período a serem considerados para o alerta. Ele é composto por:
- Operator: qualifica o valor inserido com as opções "mais de" ("more than") ou "menos de" ("less than").
- Quantity: valor de quantidade total ou porcentagem de respostas cuja ultrapassagem (ou não ultrapassagem, vide o operador escolhido no item anterior) disparará o alerta.
- Unit: unidade selecionável do valor anterior. Opções: porcentagem ou número de chamadas.
- Response Status: código HTTP que deverá ser considerado. É possível incluir um código específico (ex.: 504) ou família, utilizando xx (ex.: 5xx).
- Period / Unit: campos que compõem o período de tempo a ser considerado para a contabilização do valor inserido. Em Period, incluir o número e em Unit a unidade de tempo (opções: minutos e horas).
  
  Tempo máximo que pode ser configurado: 24 horas (ou 1440 minutos).

Compare with Past Period (comparando com tempo passado)

A seção COMPARE WITH PAST PERIOD permite comparar os valores de referência cadastrados para monitoramento com períodos passados para o disparo de notificação. Nesse caso, os valores inseridos nos campos da seção EVENT DETAILS não dispararão uma notificação quando atingidos de forma absoluta, mas sim quando atingidos em relação a uma performance passada.

Exemplo

Imagine um alerta de total de chamadas (Total Calls) que envia uma notificação quando há mais de 100 requisições utilizando uma dada operação a um dado recurso por um período de um minuto. Se não habilitarmos a comparação com um período passado, a notificação será enviada sempre que mais de 100 requisições em um minuto forem feitas.

Entretanto, se configurarmos uma comparação com o mesmo período na semana passada, a notificação só será enviada quando foram contabilizadas mais de 100 requisições por minuto em relação ao mesmo período na semana passada.

Isso significa que, se forem contabilizadas 120 requisições em um dado minuto, mas no mesmo período da semana anterior haviam sido contabilizadas 80 requisições por minuto, não haverá disparo de notificação, pois a comparação de requisições revela 40 requisições a mais, menor que o valor de referência configurado (que é de 100 requisições).

Há três opções disponíveis de período para comparação, nesta ordem: último <período> <unidade> (se o período for 2 e a unidade referência for minutos, como definido anteriormente, últimos 2 minutos, se o período for 5 e a unidade for horas, últimas 5 horas); mesmo período no dia anterior; e mesmo período na semana anterior.

Quando habilitada a comparação de performance com um período passado, os alertas do tipo Total Calls e Latency têm opções adicionadas no cadastro da seção EVENT DETAILS. Para configurar os valores de referência, existe a adição de unidade de porcentagem como opção.

No caso de Total Calls, os campos de valor de referência, ao invés de Call Qty, passam a ser:

Quantity / Unit: campos para inserir o valor de quantidade de chamadas a mais ou a menos (a depender do operador escolhido) em relação a um período passado, que, se atingido, disparará o alerta.
- Há duas opções de unidade: chamadas (calls) ou porcentagem (percent).

No caso de Latency, os campos de valor de referência, ao invés de Latency, passam a ser:

Latency / Unit: campos para inserir o valor de latência média maior ou menor (a depender do operador escolhido) do que o de um período passado, que, se atingido, disparará o alerta.
- Há duas opções de unidade: milissegundos (ms) ou porcentagem (percent).

Como os outros tipos (Availability e HTTP Response Status) já oferecem porcentagem como unidade de contabilização dos valores de referência, não há modificação nos campos quando habilitada a comparação com período passado.

Silent Interval (silenciando uma notificação temporariamente)

É possível silenciar uma notificação por um tempo pré-determinado ao habilitar a opção SILENT INTERVAL. Isso é útil, por exemplo, quando você sabe que existe um problema de indisponibilidade com sua API e quer desabilitar uma notificação somente durante um período específico, sem desabilitar o alerta completamente (veja aqui sobre como desabilitar alertas).

Para configurar o tempo de silêncio, preencha o campo que aparecerá com o intervalo desejado, composto por um número e uma unidade (minutos ou horas).

O tempo máximo que pode ser configurado é de 24 horas (ou 1440 minutos).

Se a opção permanecer sempre ligada, o alerta será habilitado depois do intervalo configurado. Então, a próxima notificação que for disparada por um evento será enviada normalmente e acionará um novo período de silêncio.

Um exemplo para esclarecer esse funcionamento:

Imagine que você estabeleça um período de silêncio de 4 horas para um alerta que envia uma notificação quando mais de 20% das requisições a uma dada API retornarem um status HTTP de erro. Durante 4 horas, seu alerta não gerará notificações. Imagine que, passadas 5 horas, o campo SILENT INTERVAL continue habilitado e aconteça de 30% das requisições obterem status de erro. Nesse caso, uma notificação será enviada e essa notificação desencadeará um novo período de silêncio de 4 horas (a partir desta última notificação).

Schedule (programando a checagem de estado)

A seção SCHEDULE define a frequência de checagem de estado para geração dos alertas. Ela contém duas opções:

Pre-defined (pré-definida). Nesse caso, completar o campo Check every <Period> com a frequência desejada. Opções: 1 minuto; 5, 10 ou 30 minutos; 1 hora; ou todos os dias às 00h.
Cron Expression. Nesse caso, uma expressão de agendamento do tipo Cron (ver quadro abaixo) deve ser inserida no campo Expression.

Uma Cron Expression é uma string que define um agendamento periódico seguindo um formato específico. O campo Cron Expression aceita agendamentos compostos por cinco campos:

<minuto> <hora> <dia do mês> <mês> <dia da semana>

Para completar os campos, podem ser usados números e alguns caracteres especiais:

* significando "todos";
? significando "qualquer" e podendo ser utilizado em mês e dia de semana;
L significando "último" e podendo ser utilizado em mês e dia de semana;
três letras iniciais de dias de semana em inglês (como MON e TUE);
, e - para indicar cortes (o primeiro considerando só os pontos indicados e o segundo considerando todo o intervalo entre eles).

Alguns exemplos:

30 10 ? * *: checagem todos os dias às 10:30 da manhã.
0 14 ? * MON-FRI: checagem de segunda a sexta, às 14:00.
0 14 ? * MON,FRI: checagem às 14:00, somente às segundas e às sextas.
0 8 * JUN ?: checagem às 8:00 da manhã, todos os dias do mês de junho.
10 17 L * ?: checagem às 17:10 no último dia de cada mês.

Depois de inserir todos os dados, o botão NEXT será habilitado e levará à próxima etapa.

Actions

A etapa ACTIONS compreende os canais de envio de notificações:

Para adicionar uma ação e configurá-la, clique em icon add .

É necessário que pelo menos uma ação seja configurada para que você possa salvar/criar o alerta.

E-mail

Quando esta ação é configurada, um email de notificação é enviado sempre que o alerta for disparado.

Para incluir destinatários, insira o endereço de email no campo E-mails, dentro da seção RECEIVERS. Você pode adicionar quantos endereços desejar, digitando-os individualmente ou inserindo múltiplos emails ao mesmo tempo, separando cada um com vírgulas.

Depois de um destinatário ter sido incluído no campo acima, ele receberá um email, como o da imagem abaixo, para que autorize o recebimento das notificações. Para confirmar, clicar sobre o botão YES, I WANT TO SEE EVERYTHING!. O link de confirmação contido no email será válido por 24 horas após o envio.
receivers email

Caso um destinatário não tenha ainda confirmado sua inscrição como recebedor, seu endereço de email será realçado em amarelo na tela de edição do alerta (veja mais sobre edição de alertas aqui).

Você pode enviar um novo email de confirmação clicando no ícone ao lado da lista de emails ( icon new email ), como na imagem abaixo:
actions email

Na seção ADD CUSTOM MESSAGE você pode inserir uma mensagem adicional personalizada a ser enviada com a notificação. Para isso, habilite o botão e inclua a mensagem no campo de edição que será aberto, como no exemplo abaixo:

A mensagem pode ser escrita em formato puro texto ou em HTML.

Ao clicar em SAVE, você voltará a visualizar o quadro de ações, e agora a ação E-mail conterá ícones para visualização de detalhes ( icon more ), edição ( icon edit ) e remoção ( icon delete ). Ao clicar em , você verá as informações configuradas:

Agora, você poderá configurar outra ação ou salvar o alerta, seguindo para a etapa REVIEW.

Slack

Quando esta ação é configurada, uma notificação é enviada para um canal do Slack sempre que o alerta for disparado.

Primeiro, selecione o workspace do Slack que será utilizado. Se você não tiver incluído um workspace na tela Integrations, pode fazer isso clicando no botão + ADD WORKSPACE. Os passos são os mesmos (veja mais sobre isso aqui). Depois de escolhido o workspace, será aberto o campo Channel para a escolha do canal, como no exemplo abaixo:

Por padrão, só serão exibidos canais públicos, mas é também possível adicionar um canal privado. Leia sobre essa configuração aqui.

Só é possível escolher um canal por alerta.

A mensagem pode ser escrita em formato puro texto ou utilizando a formatação aceita pelo Slack. Leia mais sobre isso na documentação do Slack.

Ao clicar em SAVE, você voltará a visualizar o quadro de ações, e agora a ação Slack conterá ícones para visualização de detalhes ( icon more ), edição ( icon edit ) e remoção ( icon delete ). Ao clicar em , você verá as informações configuradas:

Se desejar, pode enviar uma mensagem de teste para o canal configurado clicando em SEND TEST MESSAGE.

Agora, você poderá configurar outra ação ou salvar o alerta, seguindo para a etapa REVIEW.

Webhook

Quando você configura uma ação de Webhook, o Flexible Actions envia uma requisição HTTP POST para o endpoint que você determinar sempre que o alerta for disparado. Com isso, você consegue acionar uma API específica a partir do monitoramento do Flexible Actions. O payload dessa requisição incluirá os parâmetros monitorados do alerta e a mensagem adicional, caso você inclua uma.

Esses são os campos necessários para configurar um webhook:

ENDPOINT: inclua o endpoint no campo Url.
AUTHENTICATION: seção não obrigatória para estabelecer credenciais que o Flexible Actions deverá incluir na requisição. Cada credencial é composta por um client ID acompanhado ou não de um client secret e identificando onde elas serão trafegadas na requisição (em header ou query param). Todas as credenciais cadastradas estão listadas na tela Integrations e você pode selecionar uma credencial existente no campo Credential. Se você não tiver cadastrado a credencial que deseja usar na tela Integrations, pode fazer isso clicando no botão + NEW CREDENTIAL. Os passos são os mesmos (veja mais sobre isso aqui).

Na seção ADD CUSTOM MESSAGE você pode inserir uma mensagem adicional personalizada a ser incluída na requisição. Para isso, habilite o botão e inclua a mensagem no campo de edição que será aberto, como neste exemplo:

A mensagem será incluída no payload da requisição, identificada por "customMessage".

Ao clicar em SAVE, você voltará a visualizar o quadro de ações, e agora a ação Webhook conterá ícones para visualização de detalhes ( icon more ), edição ( icon edit ) e remoção ( icon delete ). Ao clicar em , você verá as informações configuradas:

É possível visualizar o schema JSON e uma amostra de payload que será enviado clicando no botão {…} VIEW SAMPLE.

Agora, você poderá configurar outra ação ou salvar o alerta, seguindo para a etapa REVIEW.

Review

A etapa REVIEW exibe os detalhes configurados do alerta recém-criado, como no exemplo abaixo:

As ações cadastradas conterão o ícone icon more para mais informações. Além disso, para Slack, é possível enviar uma mensagem de teste clicando em SEND TEST MESSAGE; e para Webhook é possível visualizar o schema JSON e uma amostra de payload que será enviado clicando no botão {…} VIEW SAMPLE.

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]