9 Métricas Essenciais para Medir a Saúde de uma API

Medir a saúde de uma API é mais do que saber se ela responde. Uma API pode estar no ar e ainda assim entregar uma experiência terrível, lentidão, erros intermitentes, timeouts. As métricas certas ajudam a enxergar o que está acontecendo antes que o usuário reclame. Uso estas 9 métricas no dia a dia para monitorar APIs em produção e diagnosticar gargalos. Elas cobrem desde o tempo de resposta até o impacto do banco de dados. Vou direto ao ponto.

1. Latência (Tempo de Resposta)

Latência é o tempo que a API leva para responder a uma requisição, medido em milissegundos. É a métrica mais óbvia, mas a mais enganosa se olhada só pela média. O problema: uma média baixa pode esconder picos de lentidão. Prefiro monitorar o percentil 95 (p95) e o percentil 99 (p99). Se o p99 está em 2 segundos enquanto a média está em 200 ms, você tem um grupo de requisições muito lentas.

Critério concreto: Em APIs REST para aplicações web, o p95 deve ficar abaixo de 500 ms. Acima de 1 segundo no p99, já é sinal de gargalo.

2. Throughput (Requisições por Segundo)

Throughput mede quantas requisições a API consegue processar por unidade de tempo, normalmente requisições por segundo (RPS). Ela revela a capacidade real do sistema. Uma API pode ter latência baixa com 10 RPS, mas cair para 50% de desempenho quando o tráfego sobe para 100 RPS. A métrica sozinha não basta; precisa ser correlacionada com a latência.

Critério concreto: Defina um limite de throughput máximo aceitável antes da latência degradar. Por exemplo, 500 RPS com p95 abaixo de 300 ms. Quando o throughput se aproxima desse limite, é hora de escalar.

3. Taxa de Erro (Error Rate)

Percentual de requisições que retornam código de erro HTTP (4xx ou 5xx) em relação ao total. Uma taxa de erro de 1% pode parecer baixa, mas em um sistema com 1 milhão de requisições por dia, são 10 mil falhas. Erros 5xx indicam problema no servidor; 4xx geralmente são problemas do cliente, mas um aumento súbito de 400 (Bad Request) pode indicar mudança na API que quebrou consumidores.

Critério concreto: Monitore a taxa de erro em janelas de 5 minutos. Se ultrapassar 0,5% para 5xx, acione alerta. Para 4xx, investigue se há pico anormal (mais de 5% em 1 hora).

4. Disponibilidade (Uptime)

Disponibilidade é a porcentagem de tempo em que a API está operacional e respondendo corretamente. O famoso "99,9%" (três noves) significa cerca de 8 horas de downtime por ano. Mas disponibilidade não é binária: uma API pode estar "no ar" e retornar erros internos. Por isso, uso health checks que validam não só a resposta HTTP, mas também a integridade de dependências (banco, cache).

Critério concreto: Para APIs críticas, estabeleça 99,9% de uptime com health check a cada 30 segundos. Qualquer falha no health check conta como downtime.

5. Tempo de Fila (Queue Time)

O tempo que a requisição passa esperando em fila antes de ser processada. Em arquiteturas com balanceadores de carga ou filas de mensagens (como RabbitMQ, Kafka), esse tempo pode crescer sem que a latência total dispare. Se o tempo de fila aumenta, o sistema está saturado. É um indicador antecedente: antes de a latência piorar, a fila já cresce.

Critério concreto: Monitore o tempo médio de fila. Se ultrapassar 100 ms, investigue capacidade do servidor. Acima de 500 ms, a fila já está comprometendo a experiência.

6. Uso de CPU e Memória

Métricas de infraestrutura que impactam diretamente a performance da API. CPU a 90% constante indica que o processamento está no limite; memória crescendo sem liberação sugere vazamento (memory leak). Ambas são métricas de causa, não de efeito. Quando a latência sobe, olho primeiro CPU e memória para ver se o problema é de recurso.

Critério concreto: Defina alertas: CPU > 80% por 5 minutos, memória > 85%. Para APIs em contêineres, monitore também o uso por pod.

7. Taxa de Timeout

Percentual de requisições que excedem o tempo limite configurado (timeout) e são canceladas. Timeouts são diferentes de erros 5xx: a requisição simplesmente não recebe resposta. Uma taxa de timeout alta indica que a API está sobrecarregada ou que o timeout está mal configurado. O problema é que timeouts geram retentativas, que sobrecarregam ainda mais o sistema.

Critério concreto: A taxa de timeout deve ficar abaixo de 0,1%. Se subir, aumente o timeout temporariamente (nunca como solução definitiva) e investigue a causa.

8. Tamanho da Payload

O tamanho médio dos dados enviados e recebidos em cada requisição. Payloads muito grandes aumentam a latência de rede e o tempo de serialização/desserialização. Uma API que retorna 10 MB por requisição vai sofrer com throughput baixo. É uma métrica de design: muitas vezes o problema não é a API, mas o consumidor pedindo dados demais.

Critério concreto: Monitore o p95 do tamanho da resposta. Se ultrapassar 1 MB, avalie se é possível paginar ou comprimir (gzip). Acima de 5 MB, repense o endpoint.

9. Latência de Banco de Dados

O tempo que as consultas ao banco de dados levam para retornar. É a métrica mais específica, mas a mais reveladora. Uma API pode ter lógica impecável, mas se o banco está lento, nada adianta. Consultas N+1, falta de índices ou locks de tabela são causas comuns. Costumo correlacionar a latência do banco com a latência total da API: se a primeira representa mais de 60% da segunda, o gargalo está no banco.

Critério concreto: Monitore o p95 da latência de banco. Se ultrapassar 200 ms para consultas simples, revise índices. Acima de 1 segundo, investigue queries lentas.

Como Escolher as Métricas Certas

Não precisa monitorar todas as 9 de uma vez. Comece com as três primeiras: latência (p95), throughput e taxa de erro. Elas já cobrem 80% dos cenários comuns. Depois, adicione disponibilidade e tempo de fila se a API for crítica. CPU/memória e latência de banco entram quando você começar a investigar gargalos. O segredo é ter alertas configurados para cada métrica, com thresholds baseados no comportamento histórico da sua API.

FAQ

Qual a diferença entre latência e tempo de resposta?

Na prática, são a mesma coisa: o tempo entre o envio da requisição e o recebimento da resposta. Mas latência pode incluir atrasos de rede, enquanto tempo de resposta geralmente se refere ao processamento no servidor. Para monitoramento, uso os termos como sinônimos.

Quantas requisições por segundo uma API saudável deve aguentar?

Não existe número universal. Depende da arquitetura, do hardware e do tipo de operação. Uma API de consulta leve pode aguentar 1000 RPS; uma que processa upload de arquivos, 10 RPS. O importante é definir seu baseline e monitorar a degradação.

Como medir a taxa de erro de uma API?

Através de logs ou ferramentas de APM (Application Performance Monitoring). Conte o número de respostas com código HTTP 5xx e 4xx, divida pelo total de requisições em um intervalo (ex.: 5 minutos) e multiplique por 100 para obter a porcentagem.

O que causa timeout em uma API?

Geralmente, sobrecarga do servidor (CPU/memória no limite), consultas lentas ao banco de dados, ou dependências externas lentas (outra API). Timeouts também podem ocorrer se o timeout configurado no cliente for muito baixo.

Devo monitorar todas as métricas em tempo real?

Não. Monitore latência, throughput e taxa de erro em tempo real (a cada 1-5 minutos). CPU/memória e latência de banco podem ser verificadas a cada 5-10 minutos. Tempo de fila e tamanho da payload são métricas de diagnóstico, não de alerta contínuo.

Qual ferramenta usar para monitorar métricas de API?

Ferramentas como Datadog, New Relic, Grafana com Prometheus, ou soluções open source como Prometheus + Alertmanager. Para quem começa, o New Relic tem um tier gratuito generoso. O importante é centralizar as métricas e configurar alertas.