Criando novas políticas de Runtime Alerts

Veja abaixo como configurar uma política para monitoramentos e notificações em tempo de execução.

Opções de instruções:

Como criar uma nova política

  1. Clique no botão + NEW POLICY, no canto superior direito da página Runtime Alerts.
    detalhe da tela com destaque para o botão de new policy

  2. Na tela POLICY, defina as informações básicas da política (como nome, classificação), os parâmetros do monitoramento (tipo, limites, períodos) e sua frequência.
    detalhe da tela com as informações da política

  3. Defina os itens a serem monitorados (MONITORED ITEMS), escolhendo APIs, ambientes, recursos e operações.
    Quando terminar de definir todos os itens para monitoramento, clique em ADD ITEM.
    É possível voltar depois para adicionar ou deletar APIs/eventos desta política.

  4. Você pode adicionar várias APIs para cada política. Para isso, repita o passo 3 quantas vezes forem necessárias.

    • Entenda o funcionamento das configurações fixas e dinâmicas (any e all).

    • Veja detalhes sobre os campos a serem preenchidos.

    • Não há um limite de APIs que podem ser monitoradas por uma mesma política. No entanto, recomendamos que você mantenha a quantidade de APIs monitoradas por política em um número máximo de 50, para permitir o gerenciamento eficaz das notificações.

  5. Na tela ACTIONS, selecione e configure um ou mais meios de envio da notificação, podendo ser:

  6. Revise as definições e clique em SAVE.

    É necessário clicar em SAVE para finalizar a criação da política. Configurações não salvas serão perdidas.

Leia também sobre como funciona o conceito de políticas e as definições e especificidades de cada campo dos passos acima.



Descrição detalhada

Clique nos links acima para ver os detalhes de cada campo nos passos para criar uma política.


linha horizontal com quatro círculos um para cada etapa do processo com destaque para o passo 1

1 POLICY

  • Policy info (informações da política)

    • Policy name: dê um nome para a política;

    • Classification: escolha uma classificação (Neutral (neutro), Success (sucesso), Warning (atenção) ou Critical (crítico)) e

    • Tag: se desejar, defina uma tag (etiqueta). As tags auxiliam na organização das suas políticas e podem ser utilizadas para encontrar alertas mais facilmente.


  • Monitored Event Details: (Detalhes do evento monitorado)

    • Type: defina o parâmetro que deseja monitorar, podendo ser:

      • Total Calls: quando a quantidade total de chamadas em um dado período é atingida (ou não, dependendo das configurações);

      • Availability: referente à disponibilidade de uma dada operação a um recurso.
        Uma API é considerada disponível se não retorna um erro da família 5xx;

      • Latency: latência média em dado período; ou

      • HTTP Response Status: código de estado retornado de uma chamada. Você pode informar o código específico (ex.: 504) ou família (ex.: 5xx).
        O código resposta deve estar entre 100 e 599 ou igual a 1xx, 2xx, 3xx, 4xx, 5xx.

        Você pode adicionar mais de uma família (ex.: 5xx, 4xx) ou código (ex.: 401, 403).
        Se uma família for informada, ela será considerada em detrimento de um código específico (ex.: 5xx será considerado em detrimento de 504).

    • Threshold: limiares do monitoramento. Escolha um operador de comparação (Comparison Operator), que pode ser "maior que" (more than) ou menor que (less than) e seu valor (Amount):

      • Total Calls: número total de chamadas;

      • Availability: valor em percentual da disponibilidade;

      • Latency: total em milissegundos;

      • HTTP Response Status: defina o valor e escolha se o valor é percentual ou quantidade de chamadas.

    • Period: intervalo de tempo a ser considerado para a contabilização do valor inserido.

      • Amount: defina um valor entre 1 a 1440 (para minutos) ou entre 1 a 2 (para horas);

      • Unit: escolha entre minutes (minutos) e hours (horas);

      • Past period: para habilitar este campo, selecione a caixa "Compare with past period" e informe o intervalo passado com o qual deseja comparar.

        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 MONITORED OPERATION 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 forem contabilizadas mais de 100 requisições por minuto em relação ao mesmo período na semana anterior.

        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:
        1. último <período> <unidade> (se o período configurado for 2 e a unidade referência for minutos, será últimos 2 minutos, se o período for 5 e a unidade for horas, últimas 5 horas);
        2. mesmo período no dia anterior; e
        3. mesmo período na semana anterior.

    • Minimum amount of requests to trigger actions (quantidade mínima de requisições para disparar as ações)

      • Especifique quantas chamadas com as configurações definidas precisam acontecer para que as ações (envio de alertas pelos meios escolhidos) sejam ativadas.

      • Campo válido apenas para os tipos Availability e Latency.
        Para Total Calls e HTTP Response Status, a quantidade de chamadas é definida em Threshold, selecionando a unidade Calls (chamadas).


  • Schedule: (Agendamento)
    Frequência de checagem do estado para a gerar notificações. Selecione:

    • Predefined: para predefinir o período (1, 5, 10, ou 30 minutos; 1 hora; ou todos os dias às 00h) ou

    • Cron Expression: para inserir uma expressão de agendamento do tipo Cron (quadro a seguir).

      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:

      • * significa "todos";

      • ? significa "qualquer" e pode ser utilizado em mês e dia de semana;

      • L significa "último" e pode 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 - indicam cortes (o primeiro considera só os pontos indicados e o segundo considera 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ã em todos os dias do mês de junho.
      10 17 L * ?: checagem às 17:10 no último dia de cada mês.

    • Silent interval

      É 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 apenas temporariamente (veja como desabilitar alertas permanentemente).

      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.

      Exemplo

      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).


linha horizontal com quatro círculos um para cada etapa do processo com destaque para o passo 2

2 MONITORED ITEMS

  • Adicionar API
    Defina os itens que serão monitorados.
    Selecione:

    • API Name: uma API. Aqui serão listadas as APIs que estão disponível no catálogo da API Platform;

    • Environment: um ou mais ambientes disponíveis para a API selecionada;

    • Resources: um ou mais recursos;

    • Operation: uma ou mais operações.

      Para Environment, Resources e Operation é possível também optar por:
      Select All: para que todos os ambientes sejam considerados para monitoramento (fixo) ou
      Any environment: para que todo e qualquer ambiente seja considerado para monitoramento (dinâmico).
      Veja a diferença entre All e Any

  • Lista de políticas
    Os itens adicionados para a política ficarão disponíveis nesta lista, com as colunas:

    • API Name: nome da API;

    • Summary: quantidade de ambientes, recursos e operações selecionadas para monitoramento.
      A quantidade não é exibida para itens com monitoramento dinâmico — eles são descritos como "any" (qualquer).
      Itens com monitoramento fixo são apresentados com o número que representa a quantidade total disponível (do ambiente, recurso ou operação) no momento da criação da política.

    • Actions: ações de editar ou deletar o item.


linha horizontal com quatro círculos um para cada etapa do processo com destaque para o passo 3

3 ACTIONS

A ação de enviar uma notificação pode ser configurada e personalizada nesta etapa da configuração.

Siga os passos abaixo para configurar uma ação. Clique nos links para mais detalhes.

  1. Clique em +, ao lado de uma ação.

  2. Preenchas os campos indicados.
    Clique para ver mais detalhas da configuração de envio de alerta por:

  3. Opcionalmente, habilite "Add Custom Message" e personalize a mensagem a ser enviada com a notificação.
    Disponível para: e-mail, Slack, Microsoft Teams e Webhook.

  4. Clique SAVE para salvar a configuração.
    É necessário que pelo menos uma ação seja configurada para que você possa salvar o alerta.

    Salvar a ação não salva a política. Para salvar a política, clique em SAVE no final do processo de configuração (passo 4 REVIEW).

  5. Você pode configurar mais de uma ação por política.
    Para configurar mais ações, repita os passos de 1 a 4.

  6. Clique em NEXT para seguir para o próximo passo do cadastro de política: revisão (Review).

E-mail

Quando esta ação é configurada, um e-mail de notificação é enviado sempre que algum evento que aciona um alerta acontece.

Siga os passos abaixo para configurar uma ação de envio por e-mail.

  1. Clique em + e insira um ou mais endereços de e-mail no campo E-mails.

    Use vírgulas para separar os e-mails.

  2. Se desejar, inclua uma mensagem adicional personalizada clicando em ADD CUSTOM MESSAGE.

    A mensagem pode ser escrita em formato texto simples ou HTML.
    Veja um exemplo:
    tela de configuração de e-mail com inserção de mensagem personalizada

  3. Clique em SAVE.

Depois de um destinatário ter sido incluído, ele receberá um e-mail para que autorize o recebimento das notificações. O link de confirmação contido no e-mail será válido por 24 horas após o envio.

Será enviado apenas 1 e-mail de notificação por política (e não por operação).

Slack

Quando esta ação é configurada, uma notificação é enviada para um canal do Slack sempre que algum evento que aciona um alerta acontece.

Siga os passos abaixo para configurar uma ação de envio por Slack:

  1. Clique em ] e selecione o workspace do Slack que será utilizado ou adicione um novo,clicando em btn:[ ADD WORKSPACE.
    Veja mais detalhes sobre como incluir um workspace

  2. Escolha um canal.
    Por padrão, só serão exibidos canais públicos.
    Veja como adicionar um canal privado.

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

  3. Se desejar, inclua uma mensagem adicional personalizada (clique em botão de alternar ou toggle ao lado de ADD CUSTOM MESSAGE para habilitar o campo).

    Veja um exemplo:

    tela de configuração de slack com inserção de mensagem personalizada

  4. Clique em SAVE.

  5. Se desejar enviar uma mensagem de teste: ao lado de "Slack", clique em indicação de opção de expandir para expandir e clique em SEND TEST MESSAGE.

Microsoft Teams

Quando esta ação é configurada, uma notificação é enviada para o Microsoft Teams sempre que algum evento que aciona um alerta acontece.

Siga os passos abaixo para configurar uma ação de envio por Microsoft Teams

  1. No Microsoft Teams, crie um webhook de entrada (incoming webhook).
    Veja a documentação do Microsoft Teams.

  2. Clique em + no campo "Incoming Webhook URL", informe a URL que recebeu do Microsoft Teams ao criar o Webhook de entrada.

  3. Se desejar, inclua uma mensagem adicional personalizada (clique em botão de alternar ou toggle ao lado de ADD CUSTOM MESSAGE para habilitar o campo).
    Veja um exemplo:

    tela de configuração de slack com inserção de mensagem personalizada

  4. Clique em SAVE.

  5. Se desejar enviar uma mensagem de teste: ao lado de "Microsoft Teams", clique em indicação de opção de expandir para expandir e clique em SEND TEST MESSAGE.

Webhook

Quando esta ação é configurada, sempre que algum evento que aciona um alerta acontece, uma requisição HTTP POST é enviada para o endpoint que você determinar.

Com esse alerta, você consegue acionar uma API específica. O payload dessa requisição incluirá os parâmetros monitorados do alerta e uma mensagem adicional (opcional).

Siga os passos abaixo para configurar um webhook:

  1. Clique em + e inclua a URL do endpoint.

  2. Se desejar, selecione uma credencial ou crie uma nova clicando em + NEW CREDENTIAL.
    Veja mais detalhes sobre como criar um webhook.

  3. Se desejar, inclua uma mensagem adicional personalizada (clique em botão de alternar ou toggle, ao lado de ADD CUSTOM MESSAGE para habilitar o campo).
    Veja um exemplo:
    +image::runtime-events_webhook-filled.png[]

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

  4. Clique em SAVE.

  5. Se desejar, veja um exemplo de esquema JSON ou de JSON. Clique em {…​} VIEW SAMPLE e selecione uma aba.

WhatsApp

Quando esta ação é configurada, sempre que algum evento que aciona um alerta acontece, uma mensagem é enviada por WhatsApp para um ou mais números.

Siga os passos abaixo para configurar uma ação de envio por WhatsApp:

  1. Clique em + e selecione um ou mais contatos.
    Os contatos ficam em Phone Catalog.
    Clique para ver como adicionar um novo contato.

  2. Clique em SAVE.

  3. Se desejar enviar uma mensagem de teste: ao lado de "WhatsApp", clique em indicação de opção de expandir para expandir e clique em SEND TEST MESSAGE.

Para utilizar o WhatsApp como meio de notificação, é necessário ativar o plano para seu ambiente.
Entre em contato conosco para mais detalhes.


linha horizontal com quatro círculos um para cada etapa do processo com destaque para o passo 4

4 REVIEW

Confira os detalhes e parâmetros da política.

Se precisar editar, volte aos passos anteriores, clicando na trilha de navegação (breadcrumble) no topo da página.

Ao terminar, clique em SAVE para salvar a política.

É necessário clicar em SAVE para que as configurações sejam salvas.

A política criada fica na lista de políticas.


Funcionamento

Após uma política ter sido criada, o evento de monitoramento será executado conforme os parâmetros indicados para todos os itens (APIs/Operations) selecionados e, caso seja detectado que determinada API/operation se enquadra nesse evento, a notificação escolhida na política será acionada individualmente para cada API/operation.

Acompanhe um exemplo (por vídeo ou texto).



Criei uma política para ser executada a cada 5 minutos para as seguintes APIs/Operations (Monitored Items):

  • 1. API Pedidos 1.0, Environment Production, Resource Pedidos, Operation GET/lista e GET/itens

  • 2. API Delivery 1.0, Environment Any, Resource Any, Operation Any

  • 3. API Tokens 1.0, Environment All, Resource Tokens, Operation All

Essa política vai monitorar se a quantidade de chamadas ultrapassa 10 chamadas com status code 200 nos últimos 5 minutos.

Imagine os seguintes cenários:

1. API Pedidos 1.0, Environment Production, Resource Pedidos, Operation GET /lista e GET /itens

Suponha que:

  • para a Operation GET/lista, a condição seja verdadeira, ou seja, ela teve mais que 10 chamadas com status code 200 nos últimos 5 minutos no momento da verificação e

  • para a Operation GET/itens, a condição seja falsa.

→ Então a notificação será enviada apenas para a operation GET/lista. Note que apenas o deployment da API no Environment Production será monitorado.

2. API Delivery 1.0, Environment Any, Resource Any, Operation Any

Suponha que:

  • para Operation (Any), alguma operação ultrapassou 10 chamadas com status code 200 nos últimos 5 minutos no momento da verificação

→ Então será disparada notificação para cada operation individualmente. Note que, como a verificação é realizada em qualquer (Any) Environment, as notificações serão enviadas individualmente também para cada Environment e Operation.

3. API Tokens 1.0, Environment All, Resource Tokens, Operation All

Suponha que:

  • houve alguma operação do Resource Tokens que ultrapassou 10 chamadas com status code 200 nos últimos 5 minutos no momento da verificação.

→ Então será disparada notificação para cada uma dessas operações que tiveram a condição verdadeira da política.

→ As operações desse recurso que não ultrapassaram 10 chamadas com status code 200 não serão incluídas nas notificações.

→ Com a seleção de "All" para ambientes e operações, serão considerados somente os ambientes e operações existentes no momento da criação ou edição da política. Se novos ambientes ou operações forem criados depois disso, eles não serão incluídos no monitoramento.

Por outro lado, ao escolher "Any" em algum critério da API (Environments, Resources, Operations), todas as opções dessa API serão consideradas no monitoramento, inclusive aquelas criadas após a criação ou edição da política. Veja mais detalhes em Configurações fixas ou dinâmicas.


Situações de exemplo

Condição: quantidade de chamadas ultrapassa 10 E status code 200 E últimos 5 minutos

Itens monitorados

Condição verdadeira?

Quantidade de notificações

1. API Pedidos 1.0, Environment Production, Resource Pedidos, Operation GET /list e GET /items

GET /list: Sim
GET /items: Não

Apenas 1 para GET/list que está no ambiente de produção. Mesmo que esta operação exista em outro ambiente, ela não será monitorada.

2. API Delivery 1.0, Environment Any, Resource Any, Operation Any

Sim para qualquer operação

Uma notificação por operação e por ambiente
Ex.: a cada 5 minutos, se 4 ambientes com 5 operações em cada atenderem à condição, serão enviadas 20 notificações ao todo.

3. API Tokens 1.0, Environment All, Resource Tokens, Operation All

Sim para todas as operações do Resource Token em todos os ambientes existentes no momento da criação da política

Uma notificação por operação e por ambiente, para itens existentes no momento da criação da política
Ex.: a cada 5 minutos, se 4 ambientes com 5 operações em cada (que já existiam no momento da criação da política) atenderem à condição, serão enviadas 20 notificações ao todo.

Configurações fixas ou dinâmicas (all ou any)

As opções All e Any definem se a política é fixa (os parâmetros que disparam o alerta são sempre os mesmos que você configurou/editou) ou dinâmica (os parâmetros são atualizados automaticamente com a API).

  • All: ao selecionar todos (all) os ítens (em Environment, Resource e Operation) para serem monitorados por uma política, todos os itens da API selecionados no momento da criação ou edição da política serão considerados para o disparo do alerta. Itens criados depois dessa definição, não entrarão no monitoramento.

  • Any: selecionando qualquer (any) item (em Environment, Resource e Operation) para ser monitorado por uma política, todo e qualquer item da API será considerado para monitoramento, incluindo adições à API que ocorram após a definição da política.

Usar a opção Any concede maior dinamicidade ao monitoramento, pois será atualizado automaticamente quando novas operações forem adicionadas à API.

Já a opção All permite que você mantenha fixos os parâmetros do monitoramento tal como foi configurado inicialmente. Novas adições às APIs deverão ser configuradas manualmente para que sejam incluídas nos disparos de alertas.

Veja um exemplo de como essas opções funcionam em um cenário de monitoramento de uma API no vídeo (aos 02:00).

Ficam temporariamente indisponíveis com esta atualização:

  • ícone de atenção indicação que avisa quando uma operação da API não está implantada (deployed) no ambiente selecionado para monitoramento.

  • ícone para copiar opção de clonar uma política.

    Esses recursos retornarão em lançamentos futuros.

    exemplo de monitoramento da versão anterior com as indicações
Thanks for your feedback!
EDIT

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