Ferramenta de monitoramento de API: uptime, tempo de resposta e validação a partir de 300+ locais

O monitoramento de API REST parece superficialmente com o monitoramento de uptime, mas é um trabalho diferente. Uma API é consumida por código, não por pessoas, e código é implacável de formas que um navegador não é. Um visitante humano tolera uma página que renderiza um pouco errada; uma integração que recebe um campo do tipo errado simplesmente quebra. Por isso, o monitoramento de API precisa verificar mais camadas do que apenas "o servidor respondeu", e a HostTracker as verifica em ordem, falhando na primeira que não se sustenta.

As camadas um a três são o que uma verificação de uptime comum oferece. A quatro e a cinco são o que faz disso monitoramento de API - e são as camadas onde a maioria dos incidentes reais de API realmente acontece.

Antes que qualquer coisa possa ser validada, o monitor precisa fazer a requisição que sua API espera. A superfície completa de requisição está disponível em um monitor de API:

A forma mais expressiva de validar uma resposta é escrever regras para ela. Cada regra é uma linha, as regras são combinadas com AND, e um monitor pode carregar até vinte delas. Este é o pacote inicial verificado para uma API JSON:

status isOk
header("Content-Type") contains "json"
body.json.path("$.count") gt 0
time lt 5s

Quatro linhas, e juntas elas cobrem as quatro camadas que importam: o endpoint respondeu com um 2xx, respondeu com JSON em vez de uma página de erro, o payload contém um resultado real em vez de um vazio, e tudo isso dentro do orçamento de tempo. Regras individualmente úteis do mesmo catálogo incluem body.json.path("$.status") eq "ok" para o próprio veredito de saúde de uma API, body.json.path("$.error") absent para um membro de erro aparecendo em uma resposta que, de outra forma, seria bem-sucedida, body.json.path("$.version") eq "2.4.1" para detectar um retrocesso não intencional, redirects.count eq 0 para um endpoint que deve responder diretamente, e cert.days.left gt 14 para o certificado na mesma conexão.

Sobre o que uma regra pode falar

As regras leem sujeitos a partir da resposta e os comparam. Os sujeitos cobrem o código de status; o tempo total de resposta e seus componentes de conexão, TLS, DNS, cabeçalho e corpo; o corpo bruto, junto com seu tamanho e um hash dele; consultas estruturadas no payload como JSON, XML, HTML ou YAML; cabeçalhos de resposta individuais; a URL final e a original e suas partes; a cadeia de redirecionamentos, salto a salto; os dias restantes do certificado, o emissor e os nomes; o protocolo TLS e a cifra negociados; os endereços que o DNS retornou; e o Set-Cookie. As comparações vão do óbvio - igual, menor que, maior que - até contains, startsWith, endsWith, matches para uma expressão regular, containsAny e containsAll para um conjunto, in para uma lista de valores aceitáveis, e exists, isNumber e unique.

Há também um eixo de detecção de mudanças: uma regra pode comparar o valor desta execução com o da execução anterior, então você pode confirmar que um contador nunca retrocede ou que um hash do corpo não mudou - o tipo de regra que detecta um retrocesso silencioso ou uma alteração de conteúdo não autorizada, em vez de uma queda.

Além da linguagem de regras, existe um caminho mais simples, de valor único, que já faz parte do monitoramento de API aqui há muito tempo e que, com frequência, é tudo que uma verificação precisa. Você diz ao monitor como interpretar o corpo, como selecionar um valor dentro dele, e o que esse valor deve ser:

• Interprete como JSON, e o seletor é uma expressão JSONPath.
• Interprete como XML, e o seletor é uma expressão XPath - o que torna SOAP e outros serviços XML fáceis de verificar.
• Trate como texto simples, e o seletor é uma expressão regular multilinha e sem diferenciação de maiúsculas/minúsculas.

O predicado aplicado ao valor selecionado cobre igual e diferente, menor-que e maior-que nas formas estrita e inclusiva, pertencimento a uma lista de valores aceitáveis ou exclusão dela, dentro de um intervalo numérico ou fora dele, e um teste para o valor ser nulo ou estar completamente ausente.

Toda falha nesta tabela retorna HTTP 200. Esse é todo o problema de monitorar uma API apenas pelo código de status: o transporte teve sucesso, então o transporte reporta sucesso.

Essa última linha vale a pena fazer deliberadamente. Um segundo monitor que não envia credenciais e confirma um 401 é a forma mais barata de descobrir que uma camada de autorização foi desativada acidentalmente - uma falha que nenhuma quantidade de teste positivo jamais revelaria.

Os monitores de API são executados a partir da frota pública de checkpoints da HostTracker - mais de 300 checkpoints em 158 cidades - e você escolhe quais locais um determinado monitor usa. A geografia importa mais para uma API do que para um site: um endpoint atrás de uma CDN ou de um balanceador de carga geodistribuído pode estar saudável em Frankfurt e falhando em São Paulo, e uma verificação de local único não tem como ver isso. O mesmo vale para o DNS - um registro desatualizado ou mal configurado costuma se propagar de forma desigual, o que parece uma interrupção intermitente de dentro e uma regional de fora.

Executar a partir de muitos lugares traz um risco óbvio: mais checkpoints, mais chances de uma rota de rede instável dar um alarme falso. A HostTracker resolve isso com um quórum de confirmação. Quando um checkpoint relata uma falha, a verificação é repetida em checkpoints independentes adicionais, e a mudança de estado só é confirmada quando eles concordam - por padrão, um veredito por maioria entre até sete agentes, com um mínimo de três. Você pode tornar isso mais rigoroso, exigindo um número definido de agentes para relatar a falha ou concordância total entre eles, para um endpoint em que um alerta falso é pior do que um lento.

Após a confirmação, o alerta segue o atraso que cada contato escolheu - imediatamente, ou após 3, 5, 15, 30 ou 60 minutos, ou 3, 6, 12 ou 24 horas de falha contínua - pelos nove canais de notificação: e-mail, SMS, chamada de voz, webhook, Slack e os aplicativos de mensagens Telegram, Discord, Viber, Facebook Messenger e Google Chat. O canal de webhook é como os alertas chegam a uma ferramenta de gerenciamento de incidentes ou de chat de equipe.

A verificação é uma requisição HTTP configurável mais análise de resposta, então o que ela atende decorre diretamente disso.

• APIs REST e JSON são o caso do dia a dia, e o monitoramento de API REST é o que a maioria das contas configura primeiro: um GET ou POST, cabeçalhos para a credencial, e regras JSONPath ou de asserção sobre o payload.
• GraphQL funciona como um POST com a query no corpo, depois JSONPath dentro de data - e vale a pena confirmar que o membro errors está ausente, já que o GraphQL é conhecido por responder 200 com erros dentro.
• Serviços SOAP e XML são um POST com o envelope como corpo e XPath como seletor, o que acessa a resposta exatamente da forma que a especificação prevê.
• Receptores de webhook e endpoints de callback podem ser verificados quanto à acessibilidade e à resposta que dão a uma requisição bem formada - valioso, porque um receptor que silenciosamente parou de aceitar entregas não produz nenhum erro em lugar nenhum do seu próprio sistema.
• Endpoints de health e readiness são o alvo de maior valor de todos, se você os tiver: sua aplicação já sabe se suas dependências estão saudáveis, e uma asserção sobre esse veredito transforma esse conhecimento próprio em um alerta.

O que não se encaixa é uma sequência - obter um token, usá-lo, depois excluir o recurso. Um monitor de API faz uma requisição por execução. Para uma jornada genuína de várias etapas, a verificação de transação conduzida por navegador é a ferramenta certa; para o tempo de carregamento de uma página em vez de um endpoint, veja tempo de acesso ao navegador e carregamento de página.

1. Teste o endpoint primeiro com a verificação HTTP instantânea gratuita - sem necessidade de login - para ver o status, o tempo e a resposta contra os quais você está prestes a escrever regras.
2. Adicione um monitor e escolha o tipo de monitoramento de API. Defina o método e adicione os cabeçalhos ou o corpo que o endpoint exige; emita para o monitor sua própria credencial em vez de reutilizar a de uma pessoa.
3. Escreva as asserções. Comece com o pacote de quatro linhas acima - status, tipo de conteúdo, um valor significativo do payload e um orçamento de tempo de resposta - que é um padrão genuinamente bom para quase qualquer API JSON.
4. Escolha um intervalo entre um minuto e 24 horas. Três minutos é o padrão e um ponto de partida razoável; reserve um minuto para os endpoints cuja interrupção é um incidente.
5. Escolha os locais. Duas ou três regiões onde seus consumidores realmente estão superam uma única região, e é isso que torna uma falha regional visível.
6. Adicione os contatos e defina o atraso de alerta de cada um. Nem todo mundo precisa saber do minuto um.
7. Deixe rodar por um dia, depois observe o histórico de tempo de resposta antes de apertar a regra de tempo. Um orçamento definido a partir de dados reais se sustenta; um definido a partir de um palpite acaba sendo silenciado.

Essas coisas são complementares e frequentemente confundidas. Uma plataforma de observabilidade ou APM instrumenta seu código e diz o que aconteceu dentro de uma requisição. O monitoramento externo de API fica fora da sua infraestrutura e diz o que um consumidor realmente recebe. Vale a pena ter ambos; nenhum substitui o outro.

O padrão em que a maioria das equipes acaba é monitoramento externo para detecção e telemetria interna para diagnóstico: a HostTracker diz que um endpoint quebrou, de onde e contra qual regra, e o seu próprio tracing diz por quê. Junto com isso, um monitor de consultas de banco de dados muitas vezes explica uma API que ficou lenta, e o monitoramento de carga de servidor explica o host em que ela roda.

• Uma requisição por execução. Sem troca de token, sem chamadas encadeadas. Aponte o monitor para um endpoint cuja autenticação não expira, e use uma verificação de transação quando o que você precisa provar for uma sequência.
• Vinte regras de asserção por monitor. Amplo na prática - o pacote de quatro linhas cobre a maioria dos endpoints - mas vale a pena saber antes de planejar um teste de contrato com cem regras.
• O modo de asserção substitui as configurações mais antigas de palavra-chave e status. Os dois modelos não podem ser combinados em um monitor; escolha a linguagem de regras ou o modo legado de palavra-chave, não ambos.
• Sem validação de OpenAPI ou JSON-schema. Você confirma valores e estruturas específicos, não um documento de schema inteiro.
• O corpo da requisição tem um limite de tamanho, então um payload POST muito grande não é o formato para o qual essa verificação foi criada.
• É monitoramento, não teste. O alvo certo é um endpoint somente leitura ou idempotente. Um monitor que altera dados a cada três minutos a partir de vários locais eventualmente será o motivo de um incidente, em vez de a coisa que detecta um.