DEV Community

Cover image for Observabilidade de API: O Que É e Como Implementar
Lucas
Lucas

Posted on • Originally published at apidog.com

Observabilidade de API: O Que É e Como Implementar

#api #backend #devops #monitoring

A observabilidade de API é a capacidade de entender por que sua API se comporta de determinada forma analisando a telemetria que ela emite: métricas, logs e traces. Na prática, uma API observável permite investigar incidentes, latência, erros e regressões sem precisar publicar uma nova versão apenas para adicionar mais logs.

Experimente o Apidog hoje

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. Para aprofundar o lado de alertas e verificações, veja o guia de monitoramento de API.

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"}
Enter fullscreen mode Exit fullscreen mode

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"
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

  1. Uma métrica dispara o alerta: p99 subiu.
  2. Um trace mostra onde o tempo foi gasto.
  3. 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. 
Rate     = requisições por segundo
Errors   = % de respostas 5xx e 4xx inesperadas
Duration = latência p95 e p99 por endpoint
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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:

  1. Geração de telemetria: o que seu código emite.
  2. 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. Se você usa Datadog, este passo a passo da API do Datadog mostra como enviar e consultar dados programaticamente.

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Executar um cenário de teste:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli
Enter fullscreen mode Exit fullscreen mode

Onde:

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

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Para um pipeline completo, veja o guia do Apidog CLI para CI/CD. Para todas as flags disponíveis, consulte a referência completa do CLI.

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.

Para comparar opções, veja a lista de ferramentas de teste sintético e a lista de ferramentas de monitoramento de API.

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.

Para uma configuração prática, veja o passo a passo das Tarefas Agendadas do Apidog.

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)