DEV Community

Observabilidade de API: O Que É e Como Implementar

O que a observabilidade de API realmente significa

Na teoria de controle, um sistema é observável quando você consegue inferir seu estado interno a partir de suas saídas externas. Em software, isso significa que a API deve emitir dados suficientes para responder perguntas como:

  • Qual endpoint ficou lento?
  • Qual região foi afetada?
  • Qual versão da API gerou mais erros?
  • Qual serviço interno adicionou latência?
  • Qual requisição específica falhou e por quê?

A diferença prática é esta: se um cliente relata que o checkout ficou lento às 2h da manhã para usuários de uma região específica, você não deveria precisar fazer deploy de novo para adicionar console.log. A telemetria já coletada deve permitir investigar o incidente.

Observabilidade vs monitoramento

Monitoramento e observabilidade se complementam, mas não são a mesma coisa. O monitoramento acompanha sinais conhecidos e dispara alertas quando eles passam de um limite definido. Exemplo:

  • Taxa de erro acima de 2%
  • Latência p99 acima de 500 ms
  • CPU acima de 80%
  • Endpoint /checkout retornando 5xx

A observabilidade permite fazer perguntas novas durante a investigação. Exemplo:

  • A latência aumentou apenas para POST /v2/checkout?
  • O problema acontece só na versão 2026-05 da API?
  • Há correlação com uma região específica?
  • Qual chamada downstream consumiu mais tempo?
  • Quais logs compartilham o mesmo trace_id?

Em resumo: o monitoramento diz que algo está errado; a observabilidade ajuda a encontrar a causa.

Aspecto Monitoramento Observabilidade
Pergunta respondida Um sinal conhecido está fora da faixa? Por que o sistema está se comportando assim?
Definido quando Antes do incidente Durante a investigação
Melhor para Falhas conhecidas e violações de SLO Problemas novos ou inesperados
Saída Alertas e dashboards Telemetria consultável de alta cardinalidade

Os três pilares: métricas, logs e traces

A observabilidade normalmente combina três tipos de telemetria: métricas, logs e traces. O OpenTelemetry formaliza esses dados como sinais de telemetria, junto com outros recursos como baggage, eventos e perfis em desenvolvimento.

1. Métricas

Métricas são medições numéricas agregadas ao longo do tempo. Para APIs, comece com:

  • Requisições por segundo
  • Taxa de erro
  • Latência p50, p95 e p99
  • Throughput por endpoint
  • Disponibilidade por rota crítica

Evite depender apenas de médias. Uma média de 120 ms pode esconder um p99 de 4 segundos, que é o que usuários reais podem estar sentindo.

Exemplo de métricas úteis por endpoint:

http_requests_total{method="POST", path="/v2/checkout", status="200"}
http_requests_total{method="POST", path="/v2/checkout", status="503"}
http_request_duration_ms_bucket{method="POST", path="/v2/checkout"}

Métricas são baratas de armazenar e rápidas de consultar. Use-as para dashboards, alertas e SLOs.

2. Logs

Logs registram eventos discretos com timestamp. Para observabilidade, prefira logs estruturados em JSON em vez de texto livre.

Exemplo:

{
  "timestamp": "2026-06-22T02:14:09Z",
  "level": "error",
  "method": "POST",
  "path": "/v2/checkout",
  "status": 503,
  "duration_ms": 4812,
  "trace_id": "8f3a1c9d2e7b4a16",
  "user_region": "ap-southeast-1",
  "api_version": "2026-05"
}

Campos recomendados para logs de API:

  • timestamp
  • level
  • trace_id
  • request_id
  • method
  • path
  • status
  • duration_ms
  • user_region
  • api_version
  • client_id ou tenant_id, se aplicável

O campo mais importante para correlacionar dados é o trace_id. Ele conecta logs individuais ao fluxo completo da requisição.

3. Traces

Um trace distribuído acompanha uma requisição enquanto ela passa por diferentes serviços. Cada etapa é registrada como um span.

Exemplo de fluxo:

POST /v2/checkout
├── API Gateway: 20 ms
├── Auth Service: 35 ms
├── Checkout Service: 120 ms
├── Payment Service: 3900 ms
└── Notification Service: 40 ms

Nesse exemplo, a causa da lentidão está no serviço de pagamento. Sem traces, você provavelmente começaria a investigar serviço por serviço.

Os três pilares funcionam melhor juntos:

  • Uma métrica dispara o alerta: p99 subiu.
  • Um trace mostra onde o tempo foi gasto.
  • Os logs filtrados por trace_id explicam o erro específico.

Use RED como ponto de partida

Você não precisa instrumentar tudo no primeiro dia. Para APIs, comece com o método RED:

  • Rate: quantas requisições por segundo a API processa.
  • Errors: quantas requisições falham.
  • Duration: quanto tempo as requisições levam.
Métrica Definição
Rate Requisições por segundo
Errors % de respostas 5xx e 4xx inesperadas
Duration Latência p95 e p99 por endpoint

RED funciona bem para APIs, gateways e service meshes porque é centrado em requisições. Para infraestrutura, complemente com USE: utilização, saturação, erros.

Uma abordagem prática:

  • API → RED
  • Servidor → USE
  • Banco → RED + USE, dependendo do caso

Transforme sinais em metas com SLIs e SLOs

Coletar telemetria é só o começo. Para tornar os dados acionáveis, defina SLIs e SLOs.

Um SLI é uma métrica que representa a qualidade do serviço. Exemplos:

  • SLI de disponibilidade = requisições bem-sucedidas / total de requisições
  • SLI de latência = % de requisições abaixo de 300 ms
  • SLI de erro = requisições 5xx / total de requisições

Um SLO é a meta para esse indicador. Exemplos:

  • 99,9% das requisições devem retornar sem erro em 28 dias.
  • 95% das requisições de checkout devem concluir em menos de 300 ms.
  • 99% das chamadas de autenticação devem concluir em menos de 200 ms.

Sem SLO, um gráfico de latência é apenas uma linha. Com SLO, ele vira um critério objetivo para decidir quando priorizar confiabilidade em vez de novas funcionalidades.

Instrumente com OpenTelemetry

Você pode dividir a stack de observabilidade em duas partes:

  • Geração de telemetria: o que seu código emite.
  • Backend de análise: onde você armazena e consulta os dados.

Para geração, OpenTelemetry é o padrão mais importante. Ele é um projeto da CNCF, surgiu da fusão entre OpenTracing e OpenCensus e é independente de fornecedor.

Com OpenTelemetry, você pode:

  • Gerar traces, métricas e logs
  • Padronizar nomes e atributos com convenções semânticas
  • Exportar dados via OTLP
  • Usar auto-instrumentação quando disponível
  • Enviar telemetria para diferentes backends
  • Reduzir dependência de um fornecedor específico

Para armazenamento e análise, você pode usar ferramentas como Prometheus com Grafana para métricas, ou plataformas como Datadog e Honeycomb para traces, métricas e logs.

A principal vantagem do OpenTelemetry é instrumentar uma vez e trocar o backend depois sem reescrever toda a instrumentação.

Inclua testes e verificações sintéticas

Observabilidade não deve começar apenas em produção. Testes também geram sinais úteis.

Shift left: testes de contrato em CI

Antes do deploy, testes de contrato verificam se a API ainda corresponde à especificação. Isso ajuda a detectar mudanças incompatíveis antes que cheguem aos usuários.

Cada execução de CI gera dados úteis:

  • commit
  • branch
  • ambiente
  • cenário executado
  • resultado
  • duração
  • timestamp

O Apidog CLI permite executar cenários de teste em pipelines. Ele é construído em Node.js e requer Node v16 ou superior.

Instalação:

npm install -g apidog-cli
# verificar instalação
node -v && apidog -v

Executar um cenário de teste:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli

Onde:

  • -t = ID do cenário de teste
  • -e = ID do ambiente
  • -r = formatos de relatório: cli, html, json ou junit

Para executar com dados de iteração em CSV ou JSON:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli -d ./data.csv

Para enviar um resumo do relatório para a nuvem Apidog:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli --upload-report

Monitoramento sintético em produção

Monitoramento sintético executa requisições roteirizadas contra sua API em produção, em intervalos definidos, como um usuário real faria.

Comece simples:

  • Chamar um endpoint de saúde
  • Validar status code
  • Medir latência
  • Verificar payload mínimo
  • Registrar falhas

Uma verificação de saúde da API é o ponto inicial. O monitoramento sintético expande isso para fluxos de várias etapas, como login, criação de recurso e checkout.

Essas verificações também são sinais de observabilidade. Uma execução sintética falhando às 02:00 com duração de 4 segundos deve ser correlacionável com logs, métricas e traces.

Gerando sinais recorrentes com Tarefas Agendadas do Apidog

O Apidog pode gerar sinais sintéticos recorrentes por meio de Tarefas Agendadas. O recurso executa automaticamente cenários de teste em horários definidos, captura resultados e ajuda em testes de regressão agendados.

Você encontra o recurso no módulo de Testes, em Tarefas Agendadas. Ao configurar uma tarefa, defina:

  • Cenários de Teste: um ou mais cenários para executar.
  • Modo de Execução: por exemplo, todo domingo às 23h ou a cada 6 horas.
  • Notificação: após cada execução ou apenas em caso de falha.

Pontos importantes:

  • Tarefas Agendadas estão em Beta.
  • O recurso requer um Runner auto-hospedado configurado.
  • As opções atuais de "Executar Em" listam Runner auto-hospedado.
  • Apidog Cloud aparece como "em breve".
  • O número de execuções depende do plano de assinatura.

O benefício é fechar o ciclo: você projeta e testa a API, depois executa os mesmos cenários periodicamente para gerar sinais de aprovação, falha e latência.

Um caminho prático para tornar sua API observável

Se você está começando do zero, siga esta ordem:

  1. Padronize logs estruturados - Use JSON. Inclua trace_id, request_id, método, rota, status e duração. Evite logs de texto livre para eventos importantes.

  2. Adicione correlação por requisição - Gere ou propague um trace_id. Inclua o mesmo ID em logs, traces e respostas de erro quando fizer sentido.

  3. Instrumente com OpenTelemetry - Comece pelos endpoints críticos. Exporte traces e métricas via OTLP. Mantenha atributos consistentes, como http.method, http.route e http.status_code.

  4. Monitore RED - Rate, Errors, Duration com p95 e p99.

  5. Defina SLIs e SLOs - Disponibilidade, latência, taxa de erro. Janelas de medição, como 7, 14 ou 28 dias.

  6. Adicione testes de contrato ao CI - Execute cenários em cada pull request ou antes do deploy. Exporte relatórios em junit ou json quando precisar integrar com outras ferramentas.

  7. Execute verificações sintéticas - Comece com health checks. Evolua para fluxos críticos. Agende execuções recorrentes.

  8. Correlacione tudo - Métrica aponta o sintoma. Trace mostra o caminho. Log explica o evento. Teste sintético confirma impacto externo.

Você não precisa implementar tudo de uma vez. Só migrar de logs de texto livre para logs JSON com trace_id já melhora bastante sua capacidade de investigação.

Checklist rápido

Use este checklist para revisar sua API:

  • [ ] Logs são estruturados em JSON
  • [ ] Cada requisição tem trace_id ou request_id
  • [ ] Erros incluem contexto suficiente para debug
  • [ ] Latência é medida por percentis, não apenas média
  • [ ] Métricas RED existem por endpoint crítico
  • [ ] Há SLOs definidos para disponibilidade e latência
  • [ ] Traces mostram chamadas entre serviços
  • [ ] Testes de contrato rodam em CI
  • [ ] Verificações sintéticas rodam em produção
  • [ ] Alertas apontam para sintomas acionáveis

Perguntas frequentes

O que é observabilidade de API?

Observabilidade de API é a capacidade de entender o estado interno de uma API a partir da telemetria que ela emite: métricas, logs e traces. Uma API observável permite investigar por que ela se comporta de certa maneira sem adicionar nova instrumentação primeiro.

Observabilidade de API e monitoramento são a mesma coisa?

Não. Monitoramento acompanha sinais predefinidos e alerta quando eles cruzam limites. Observabilidade permite fazer perguntas novas durante a investigação. O monitoramento informa que algo está errado; a observabilidade ajuda a descobrir por quê.

Quais são os três pilares da observabilidade?

Os três pilares são métricas, logs e traces. Métricas mostram números agregados, logs registram eventos discretos e traces acompanham uma requisição entre serviços.

Como tornar uma API observável?

Comece com logs estruturados e trace_id em cada requisição. Depois, adicione OpenTelemetry, métricas RED, SLIs, SLOs, testes de contrato em CI e verificações sintéticas em produção.

OpenTelemetry é obrigatório?

Não. Observabilidade é uma propriedade do sistema, não uma ferramenta específica. Mas OpenTelemetry é um padrão CNCF independente de fornecedor e facilita instrumentar uma vez para enviar dados a diferentes backends, como Prometheus, Datadog ou Honeycomb.

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.