Configurar alertas e notificações

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

As condições de alerta definem um código de status específico (por exemplo, 404/502/2xx/4xx/5xx), latência e limites de código de falha que, quando excedidos alertas acionados acionam a IU e enviam notificações por meio de vários canais, como e-mail, slack, pagerduty ou webhooks. Você pode configurar alertas no ambiente, no proxy de API, no serviço de destino ou no nível de região. Quando um alerta é acionado, você recebe uma notificação usando o método definido ao adicionar alertas e notificações.

Por exemplo, você pode acionar um alerta e enviar uma notificação à equipe de operações quando a taxa de erro 5xx exceder 23% por um período de cinco minutos para o proxy da API de pedidos de produção implantado no ambiente de produção.

A figura a seguir mostra como os alertas são exibidos na IU:

Veja a seguir um exemplo de uma notificação por e-mail que você pode receber quando um alerta é acionado.

No corpo da notificação de alerta, clique nos seguintes links para ver mais informações:

  • Mais detalhes, incluindo as configurações de alertas e a atividade de cada condição na última hora.
  • Definição de alerta para ver a definição do alerta.
  • Histórico de alertas para ver mais informações sobre o alerta específico.
  • Consulte o manual para conferir as ações recomendadas, se disponíveis.
  • Visualize o relatório da análise da API para visualizar um relatório personalizado sobre a condição de alerta.

As seções a seguir descrevem como configurar e gerenciar alertas e notificações.

Sobre os tipos de alerta

A versão inicial da API Monitoring permite criar regras baseadas em padrões que especificam quando gerar um alerta com base em um conjunto de condições predefinidas. Esses tipos de alertas são chamados de alertas corrigidos e eram o único tipo de alerta compatível com a versão inicial da API Monitoring.

Por exemplo, você pode gerar um alerta fixed quando:

  • [taxa de erros 5xx] [é maior que] [10%] por [10 minutos] de [segmentar mytarget1]
  • [contagem de erros 2xx] [é menor que] [50] por [5 minutos] em [região us-east-1]
  • [p90 latência] [é maior que] [750 ms] por [10 minutos] em [proxy myproxy1]

A versão Beta do relatório de segurança de 19.11.13 adiciona novos tipos de alertas:

  • Alertas de Tráfego total (Beta) Um tipo de alerta que permite gerar um alerta quando o tráfego muda por uma porcentagem especificada ao longo de um período.
  • Alertas de Anomalia (Beta) Um tipo de alerta em que o Edge detecta problemas de tráfego e desempenho em vez de você precisar predeterminá-los por conta própria. Em seguida, você pode gerar um alerta para essas anomalias.
  • Alertas de expiração de TLS (Beta). Um tipo de alerta que permite gerar uma notificação quando um certificado TLS está prestes a expirar.

Como o Monitoring na API agora é compatível com vários tipos de alertas, a caixa de diálogo Criar alerta agora mostra a opção de selecionar o tipo de alerta:

A caixa de diálogo de criação de alertas agora tem vários tipos de alerta.

Ver configurações de alerta

Para visualizar as configurações de alerta que estão definidas no momento, clique em Analisar > Regras de alerta na IU do Edge.

A página de alertas é exibida, conforme mostrado na figura a seguir:

E-mail de alerta

Como destacado na figura, a página Alerta permite que você:

Ver o histórico de alertas que foram acionados para sua organização

Para ver o histórico de alertas que foram acionados para sua organização nas últimas 24 horas, clique em Analisar → Regras de alerta na IU do Edge e clique na guia Histórico.

A página "Histórico de alertas" é exibida.

Histórico do alerta

Clique no nome do alerta para ver os detalhes do alerta no painel de investigação. É possível filtrar a lista pesquisando em todo ou parte do nome do alerta.

Adicionar alertas e notificações

Para adicionar alertas e notificações:

  1. Clique em Analisar > Regras de alerta na interface do usuário do Edge.
  2. Clique em +Alerta.
  3. Digite as seguintes informações gerais sobre o alerta:
    Campo Descrição
    Nome do alerta Nome do alerta. Use um nome que descreva o acionador e que seja significativo para você. O nome não pode ter mais de 128 caracteres.
    Tipo de alerta Selecione Fixo. Para saber mais sobre os tipos de alerta, consulte Sobre os tipos de alerta.
    Descrição Descrição do alerta.
    Ambiente Selecione o ambiente na lista suspensa.
    Status Alterne para ativar ou desativar o alerta.
  4. Defina a métrica, o limite e a dimensão da primeira condição que acionará o alerta.
    Campo de condição Descrição
    Métrica

    Selecione uma das métricas a seguir:

    • Código de status: selecione um código de status na lista, como 401, 404, 2xx, 4xx ou 5xx HTTP.

      Observação:

      • A API permite definir um intervalo maior de códigos de status. Use a API para especificar qualquer código de status entre 200-299, 400-599 e os valores curinga de 2xx, 4xx ou 5xx. Consulte Criar alerta.
      • Para alertas de limitação de taxa (código de status HTTP 429), defina a métrica como um código de falha de Arpike.
      • Use a política AssignMessage para reescrever o código de resposta HTTP, seja de um erro de proxy ou de erro de destino. A API Monitoring ignora todos os códigos reescritos e registra os códigos de resposta HTTP reais.
    • Latência: selecione um valor de latência na lista suspensa. Especificamente: p50 (50º percentil), p90 (90º percentil), p95 (95º percentil) ou p99 (99º percentil). Por exemplo, selecione p95 para configurar um alerta que é acionado quando a latência de resposta para o 95o percentil é maior que o limite definido abaixo.
    • Código de falha: selecione uma categoria, uma subcategoria e um código de falha na lista. Ou selecione uma das seguintes opções em uma categoria ou subcategoria:

      • Todos: total combinado em todos os códigos de falha nesta categoria/subcategoria precisa atender aos critérios da métrica.
      • Qualquer: o código de falha único nessa categoria/subcategoria precisa atender aos critérios de métrica.

      Consulte Referência do código de falha para mais informações.

    • Tráfego total (Beta): selecione o aumento ou a diminuição do tráfego. Veja a seção Alertas de tráfego (Beta) para saber mais.

    Limite

    Configure o limite da métrica selecionada:

    • Código de status: defina o limite como uma taxa percentual, contagem ou transações por segundo (TPS) ao longo do tempo.
    • Latência: selecione o limite como uma duração de latência total ou total (ms) ao longo do tempo. Nesse caso, um alerta é acionado se o percentil observado for observado, que é atualizado a cada minuto se houver tráfego, excede a condição de limite para o período que abrange a duração especificada. Ou seja, a condição limite não é agregada durante a duração total.
    • Código de falha: defina o limite como uma taxa percentual, contagem ou transações por segundo (TPS, na sigla em inglês) ao longo do tempo.
    Dimensão Clique em + Adicionar dimensão e especifique os detalhes da dimensão para os quais retornar o proxy da API, o serviço de destino ou o aplicativo do desenvolvedor e a região.

    Se você definir uma dimensão específica como:

    • Todas: todas as entidades na dimensão precisam atender aos critérios de métrica. Não é possível selecionar Todas em uma métrica do tipo Latência.
    • Qualquer: aplicável somente à região. Uma entidade na dimensão precisa atender aos critérios de métrica para qualquer região.
      Observação: para proxies de API ou serviços de destino, selecione uma coleção compatível com qualquer funcionalidade.
    • Coleções: selecione uma coleção na lista para especificar o conjunto de proxies de API ou serviços de destino. Nesse caso, qualquer entidade na coleção deve atender aos critérios.

    Se você definir a dimensão como Segmentação, poderá selecionar um serviço de destino ou o serviço especificado por uma política ServiceCalling. O destino de uma Política de destaque de serviço é exibido como um valor prefixado por "sc://". Por exemplo, "sc://my.endpoint.net".

  5. Clique em Mostrar dados da condição para exibir os dados recentes da condição na última hora.
    A taxa de erro no gráfico é exibida em vermelho quando excede o limite da condição de alerta.
    Mostrar dados de condições

    Clique em Ocultar dados de condição para ocultar os dados.

  6. Clique em + Adicionar condição para incluir outras condições e repetir as etapas 4 e 5.

    Observação: se você especificar várias condições, o alerta será acionado quando todas elas forem atendidas.

  7. Clique em Criar relatórios de análise da API com base nas condições do alerta se quiser criar um relatório personalizado com base nas condições de alerta configuradas. Essa opção ficará esmaecida se você não for um administrador da organização.

    Para mais informações, consulte Criar um relatório personalizado a partir de um alerta.

    Observação: é possível modificar o relatório personalizado depois de salvar o alerta, conforme descrito em Como gerenciar relatórios personalizados.

  8. Clique em + Notificação para adicionar uma notificação de alerta.
    Detalhes da notificação Descrição
    Canal Selecione o canal de notificação que você quer usar e especifique o destino: Email, Slack, PagerDuty ou Webhook.
    Destino Especifique o destino com base no tipo de canal selecionado:
    • E-mail: endereço de e-mail, como joe@company.com
    • Slack: URL do canal do Slack, como https://hooks.slack.com/services/T00000000/B00000000/XXXXX
    • PagerDuty: código do PagerDuty, como o abcd1234efgh56789
    • Webhook: URL do webhook, como https://apigee.com/test-webhook. Consulte Formato do objeto Webhook para ver uma descrição do objeto enviado ao URL.

      Passe todas as informações de credenciais no URL do webhook. Por exemplo: https://apigee.com/test-webhook?auth_token=1234_abcd.

      É possível especificar o URL de um endpoint que consegue analisar o objeto do webhook para modificá-lo ou processá-lo. Por exemplo, é possível especificar o URL para uma API, como a Edge ou qualquer outro endpoint que processe o objeto.

      Observação: é possível especificar apenas um destino por notificação. Para especificar vários destinos para o mesmo tipo de canal, adicione mais notificações.

  9. Para adicionar outras notificações, repita a etapa 8.
  10. Se você adicionou uma notificação, configure os seguintes campos:
    Campo Descrição
    Playbook (Opcional) Campo de texto livre para fornecer uma breve descrição das ações recomendadas para resolver os alertas quando eles forem disparados. Também é possível especificar um link para o wiki interno ou a página da comunidade em que você indica as práticas recomendadas. As informações neste campo serão incluídas na notificação. O conteúdo nesse campo não pode exceder 1.500 caracteres.
    Limitar Frequência de envio de notificações. Selecione um valor na lista suspensa. Os valores válidos incluem: 15 minutos, 30 minutos e 1 hora.
  11. Clique em Salvar.

Formato de objeto do webhook

Se você especificar um URL de webhook como destino de uma notificação de alerta, o objeto enviado ao URL terá o seguinte formato:
{
  "alertInstanceId": "event-id",
  "alertName": "name",
  "org": "org-name",
  "description": "alert-description",
  "alertId": "alert-id",
  "alertTime": "alert-timestamp",
  "thresholdViolations":{"Count0": "Duration=threshold-duration Region=region Status Code=2xx Proxy=proxy Violation=violation-description"
  },
  "thresholdViolationsFormatted": [
    {
      "metric": "count",
      "duration": "threshold-duration",
      "proxy": "proxy",
      "region": "region",
      "statusCode": "2xx",
      "violation": "violation-description"
    }
  ],
  "playbook": "playbook-link"
}

As propriedades thresholdViolations e thresholdViolationsFormatted contêm detalhes sobre o alerta. A propriedade thresholdViolations contém uma única string com os detalhes, enquanto thresholdViolationsFormatted contém um objeto que descreve o alerta. Normalmente, a propriedade thresholdViolationsFormatted é usada porque é mais simples de decodificar.

O exemplo acima mostra o conteúdo dessas propriedades para um alerta fixed quando você configura a métrica de alerta para ser acionada com base no código de status HTTP 2xx, conforme indicado pelo statusCode.

O conteúdo dessas propriedades depende do tipo de alerta, como fixo ou anomalia, e a configuração específica do alerta. Por exemplo, se você criar um alerta fixo com base em um código de falha, a propriedade thresholdViolationsFormatted conterá uma propriedade faultCode em vez de uma propriedade statusCode.

A tabela a seguir mostra todas as propriedades possíveis da propriedade thresholdViolationsFormatted para diferentes tipos de alerta:

Tipo de alerta Possível conteúdo thresholdViolationsFormatted
Correções
metric, proxy, target, developerApp,
region, statusCode, faultCodeCategory, faultCodeSubCategory,
faultCode, percentile, comparisonType, thresholdValue,
triggerValue, duration, violation
Tráfico total
metric, proxy, target, developerApp,
region, comparisonType, thresholdValue, triggerValue,
duration, violation
Anomalia
metric, proxy, target, region,
statusCode, faultCode, percentile, sensitivity,
violation
Expiração de TLS
envName, certificateName, thresholdValue, violation

Criar um relatório personalizado a partir de um alerta

Para criar um relatório personalizado a partir de um alerta:

  1. Ao criar um alerta, clique em Criar um relatório de análise da API com base nas condições de alerta, conforme descrito em Como adicionar alertas e notificações.

    Depois que você salva o alerta, a IU exibe a seguinte mensagem:

    Alert alertName saved successfully. To customize the report generated, click here.

    Clique na mensagem para abrir o relatório em uma nova guia com os campos relevantes pré-preenchidos. Por padrão, o relatório personalizado é nomeado: API Monitoring Generated alertName

  2. Edite o relatório personalizado conforme desejado e clique em Save.
  3. Clique no nome do relatório na lista e gere o relatório personalizado.

Para gerenciar o relatório personalizado criado com base nas condições de alerta:

  1. Clique em Analisar > Regras de alerta na interface do usuário do Edge.
  2. Clique na guia Configurações.
  3. Na coluna "Relatórios", clique no relatório personalizado associado ao alerta que você quer gerenciar.

    A página do relatório personalizado é exibida em uma nova guia. Se a coluna "Relatórios" estiver em branco, um relatório personalizado ainda não foi criado. Se quiser, edite o alerta para adicionar um relatório personalizado.

  4. Edite o relatório personalizado conforme desejado e clique em Save.
  5. Clique no nome do relatório na lista e gere o relatório personalizado.

Ativar ou desativar um alerta

Para ativar ou desativar um alerta:

  1. Clique em Analisar > Regras de alerta na interface do usuário do Edge.
  2. Clique no botão na coluna "Status" associada ao alerta que você quer ativar ou desativar.

Editar um alerta

Para editar um alerta:

  1. Clique em Analisar > Regras de alerta na interface do usuário do Edge.
  2. Clique no nome do alerta que você quer editar.
  3. Edite o alerta conforme necessário.
  4. Clique em Salvar.

Excluir um alerta

Para excluir um alerta:

  1. Clique em Analisar > Regras de alerta na interface do usuário do Edge.
  2. Posicione o cursor sobre o alerta que você quer excluir e clique em no menu de ações.

A Apigee sugere que você configure os seguintes alertas para ser notificado sobre problemas comuns. Alguns desses alertas são específicos para a implementação das APIs e são úteis apenas em determinadas situações. Por exemplo, vários alertas mostrados abaixo serão aplicáveis somente se você estiver usando a política ServiceCalling ou a JavaCallout.

Alerta Exemplo de IU Exemplo de API
Códigos de status 5xx para todas/quaisquer APIs Configurar um alerta de código de status 5xx para um proxy de API Configure um alerta de código de status 5xx para um proxy de API usando a API
Latência P95 para um proxy de API Configurar um alerta de latência P95 para um proxy de API Configurar um alerta de latência P95 para um proxy de API usando a API
Códigos de status 404 (Aplicativo não encontrado) para todos os proxies de API Configure um alerta de código de status 404 (Aplicativo não encontrado) para todos os proxies de API Configurar um alerta de código de status 404 (Aplicativo não encontrado) para todos os proxies de API usando a API
Contagem de proxy de API para APIs Configurar um alerta de contagem de proxies de API para APIs Configurar um alerta de contagem de proxy de API para APIs usando a API
Taxas de erro para serviços de destino Configurar um alerta de taxa de erro para serviços de destino Configurar um alerta de taxa de erro para serviços de destino usando a API
Taxas de erro para políticas ServiceCallout (se aplicável) Configurar um alerta de taxa de erros para a política de destaque de serviço Configurar um alerta de taxa de erros para a política de destaque de serviço usando a API
Códigos de falha específicos, incluindo:
  • Erros de protocolo da API (normalmente 4xx)
    • IU: Protocolo de API > Todos
    • API:
      "faultCodeCategory":"API Protocol",
      "faultCodeSubCategory":"ALL"
  • Erros HTTP "pega-tudo"
    • IU: Gateway > Outro > Gateway HTTPErrorResponseCode
    • API:
      "faultCodeCategory": "Gateway",
      "faultCodeSubCategory": "Others",
      "faultCodeName": "Gateway HTTPErrorResponseCode"
  • Erros de execução de chamadas de serviço Java (se aplicável)
    • IU: Política de execução > Java Callout > JavaCallout ExecutionFailed
    • API:
      "faultCodeCategory": "Execution Policy",
      "faultCodeSubCategory": "Java Callout",
      "faultCodeName": "JavaCallout ExecutionFailed"
  • Erros de execução de script de nó (se aplicável)
    • IU: Política de execução > Node Script > NodeScript ExecutionError
    • API:
      "faultCodeCategory": "Execution Policy",
      "faultCodeSubCategory": "Node Script",
      "faultCodeName": "NodeScript ExecutionError"
  • Violações de cota
    • UI: Política de gerenciamento de tráfego > Cota > Violação de cota
    • API:
      "faultCodeCategory": "Traffic Mgmt Policy",
      "faultCodeSubCategory": "Quota",
      "faultCodeName": "Quota Violation"
  • Erros de política de segurança
    • IU: Política de segurança > Qualquer
    • API:
      "faultCodeCategory": "Security Policy",
      "faultCodeName": "Any"
  • Erros do Sense (se aplicável)
    • IU: Detectar > Detectar > Detectar RaiseFault
    • API:
      "faultCodeCategory": "Sense",
      "faultCodeSubCategory": "Sense",
      "faultCodeName": "Sense RaiseFault"
  • Erros de execução de chamadas de serviço (se aplicável)
    • IU: Política de execução > Service Callout > ServiceCallout ExecutionFailed
    • API:
      "faultCodeCategory": "Execution Policy",
      "faultCodeSubCategory": "Service Callout",
      "faultCodeName": "ServiceCallout ExecutionFailed"
  • Erros de destino
    • IU: Gateway > Destino > Gateway TimeoutWithTargetOrCallout
    • API:
      "faultCodeCategory": "Gateway",
      "faultCodeSubCategory": "Target",
      "faultCodeName": "Gateway TimeoutWithTargetOrCallout"
  • Erros de destino, nenhum destino ativo
    • IU: Gateway > Destino > Gateway TargetServerConfiguredInLoadBalancersIsDown
    • API:
      "faultCodeCategory": "Gateway",
      "faultCodeSubCategory": "Target",
      "faultCodeName": "Gateway TargetServerConfiguredInLoadBalancerIsDown
  • Erros de destino, EOF inesperado
    • IU: Gateway > Destino > Gateway InexpectedEOFAtTarget
    • API:
      "faultCodeCategory": "Gateway", "faultCodeSubCategory": "Target", "faultCodeName" : "Gateway UnexpectedEOFAtTarget"
  • Erros de host virtual
    • IU: Gateway > Host virtual > VirtualHost InvalidKeystoreOrTrustStore
    • API:
      "faultCodeCategory": "Gateway",
      "faultCodeSubCategory": "Virtual Host",
      "faultCodeName": "VirtualHost InvalidKeystoreOrTrustStore"
Configurar um alerta de código de falhas de política Configurar um alerta de código de falha de política usando a API

Configurar um alerta de código de status 5xx para um proxy de API

Veja a seguir um exemplo de como configurar um alerta usando a IU que é acionada quando as transações por segundo (TPS) dos códigos de status 5xx para o proxy da API de hotéis excedem 100 por 10 minutos para qualquer região. Para mais informações, consulte Adicionar alertas e notificações.

Para informações sobre como usar a API, consulte Configurar um alerta de código de status 5xx para um proxy usando a API.

Configurar um alerta de latência P95 para um proxy de API

Veja a seguir um exemplo de como configurar um alerta usando a IU que é acionada quando a latência de resposta total do 95º percentil é maior que 100 ms para 5 minutos para o proxy da API de hotéis para qualquer região. Para mais informações, consulte Adicionar alertas e notificações.

Para informações sobre como usar a API, consulte Configurar um alerta de latência P95 para um proxy de API usando a API.

Configurar um alerta 404 (Aplicativo não encontrado) para todos os proxies de API

Veja a seguir um exemplo de como configurar um alerta usando a IU acionada quando a porcentagem de códigos de status 404 para todos os proxies de API excede 5% por 5 minutos para qualquer região. Para mais informações, consulte Adicionar alertas e notificações.

Para informações sobre como usar a API, consulte Configurar um alerta 404 (Aplicativo não encontrado) para todos os proxies de API que usam a API.

Configurar um alerta de contagem de proxy de API para APIs

Veja a seguir um exemplo de como configurar um alerta usando a IU que é acionada quando a contagem de código 5xx para APIs excede 200 por 5 minutos para qualquer região. Neste exemplo, as APIs são capturadas no conjunto de proxies de API críticos. Confira mais informações:

Para informações sobre como usar a API, consulte Configurar um alerta de contagem de proxy da API para APIs que usam a API.

Configurar um alerta de taxa de erro para serviços de destino

Veja a seguir um exemplo de como configurar um alerta usando a IU que é acionada quando a taxa de código 500 dos serviços de destino excede 10% para uma hora para qualquer região. Neste exemplo, os serviços de destino são capturados na coleção de destinos críticos. Confira mais informações:

Para informações sobre como usar a API, consulte Configurar um alerta de taxa de erro para serviços de destino usando a API.

Configurar um alerta de taxa de erro para a política ServiceCallout

Veja a seguir um exemplo de como configurar um alerta usando a IU acionada quando a taxa de código 500 do serviço especificado pela política ServiceCallout excede 10% por 1 hora para qualquer região. Confira mais informações:

Para informações sobre como usar a API, consulte Configurar um alerta de taxa de erro para a política de chamada de serviço usando a API.

Configurar um alerta de código de falha da política

Veja a seguir um exemplo de como configurar um alerta usando a IU que é acionada quando a contagem de código de falha JWT AlgorithmMismatch para a política VerifyJWT é maior que 5 por 10. minutos para todas as APIs. Confira mais informações:

Para informações sobre como usar a API, consulte Configurar um alerta de código de falha para o código de falha da política usando a API.