Tutorial de Observabilidade: Como Monitorar APIs em Tempo Real

No desenvolvimento de software moderno, "funcionar" não é mais suficiente. Saber como e por que algo está funcionando (ou falhando) é o diferencial entre uma aplicação boa e uma excelente. É aqui que entra a Observabilidade.

Para profissionais que gerenciam APIs, seja em uma startup ou em uma grande empresa, a falta de visibilidade sobre o que acontece em tempo real pode transformar pequenos problemas em grandes incidentes. Neste tutorial, vamos mergulhar na prática de como monitorar APIs, capturando dados vitais para manter a saúde do seu sistema.

Se você quer aprofundar seus conhecimentos em arquitetura de sistemas, confira nosso guia sobre Padrões de Arquitetura de Microserviços no blog da Downfor.

O que é Observabilidade e por que é crucial?

Muitas vezes confundida com monitoramento tradicional, a observabilidade vai além. Enquanto o monitoramento te avisa que algo quebrou, a observabilidade permite que você faça perguntas sobre o seu sistema e obtenha respostas, mesmo sobre cenários que você não previu.

Segundo o Google SRE Book, a observabilidade é composta por três pilares principais:

Logs: Registros discretos de eventos que ocorreram em um momento específico.
Métricas: Dados numéricos agregados ao longo do tempo (ex: uso de CPU, latência média).
Traces: O rastreamento de uma solicitação completa enquanto ela percorre vários serviços.

Dominar esses três pilares é essencial para qualquer carreira em DevOps ou SRE. Se você está interessado nessa área, recomendamos a leitura de nosso artigo sobre Carreira em SRE: O Guia Definitivo.

Métricas Essenciais: Os "Três Pilares do Ouro"

Antes de sair codando, precisamos definir o que vamos monitorar. No contexto de APIs, existem métricas que são indicadores universais de saúde. Chamamos isso de "The Golden Signals" (Sinais de Ouro).

1. Latência

A latência mede o tempo que uma requisição leva para ser processada. Cuidado: a latência média pode ser enganosa. É crucial monitorar a latência percentil (como p95 ou p99).

Exemplo: Se sua latência média é 200ms, mas seu p99 é 2s, significa que 1 em cada 100 usuários está tendo uma experiência terrível.

2. Tráfego

Uma medida de demanda, geralmente em Requests Per Second (RPS). Entender seus picos de tráfego ajuda no capacity planning (planejamento de capacidade).

3. Erros

A taxa de requisições que falharam. Erros HTTP 5xx indicam problemas no servidor, enquanto 4xx podem indicar problemas no cliente ou na API itself.

4. Saturação

Quão "cheio" está o seu serviço? Isso inclui CPU, memória, disco e largura de banda de rede.

Implementando Monitoramento: Um Guia Prático com OpenTelemetry

Existem diversas ferramentas no mercado (Prometheus, Grafana, Datadog, New Relic), mas o padrão da indústria para instrumentação hoje é o OpenTelemetry (OTel). Ele permite que você gere dados de telemetria de forma agnóstica ao fornecedor.

Vamos ver como instrumentar uma API simples em Node.js para capturar essas métricas.

Passo 1: Instalando Dependências

Primeiro, crie um diretório para o seu projeto e inicialize o npm:

npm init -y

Agora, instale o SDK do OpenTelemetry para métricas e tracing:

npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations

Passo 2: Configurando a Instrumentação

Para este tutorial, utilizaremos exporters de console para que você possa ver os dados funcionando localmente sem precisar configurar um backend complexo como o Prometheus ou o Jaeger imediatamente.

Crie um arquivo chamado instrumentation.js na raiz do seu projeto. Adicione o seguinte código:

// instrumentation.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace-node');
const { ConsoleMetricExporter, PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const { getResource } = require('@opentelemetry/resources');

// Inicializa o SDK do OpenTelemetry
const sdk = new NodeSDK({
  // Configura o exportador de Traces (rastreamento)
  traceExporter: new ConsoleSpanExporter(),
  
  // Configura o exportador de Métricas
  metricReader: new PeriodicExportingMetricReader({
    exporter: new ConsoleMetricExporter(),
    exportIntervalMillis: 1000, // Exporta métricas a cada 1 segundo
  }),
  
  // Adicione instrumentações automáticas (http, fs, etc)
  instrumentations: [],
});

// Inicializa o SDK
sdk.start();

Nota: Certifique-se de que o arquivo package.json tenha o tipo definido como "module" ou use a sintaxe require compatível com o seu ambiente Node.js. Para ambientes de produção, você substituiria ConsoleSpanExporter e ConsoleMetricExporter por exporters reais, como o OTLPTraceExporter para enviar dados para o Grafana ou Jaeger.

Passo 3: Criando a API Monitorada

Agora, vamos criar uma API simples que será automaticamente instrumentada pelo OpenTelemetry (se configurarmos as instrumentações automáticas) ou podemos criar métricas customizadas.

Crie um arquivo server.js:

// server.js
const express = require('express');
const app = express();
const PORT = 3000;

// Simulando uma rota que pode falhar
app.get('/api/status', (req, res) => {
    const isHealthy = Math.random() > 0.2; // 80% de chance de sucesso

    if (isHealthy) {
        res.json({ status: 'ok', uptime: process.uptime() });
    } else {
        res.status(500).json({ status: 'error', message: 'Database connection failed' });
    }
});

app.listen(PORT, () => {
    console.log(`API rodando em http://localhost:${PORT}`);
});

Para rodar isso com a instrumentação ativa, usamos a flag -r (require) do Node:

node -r ./instrumentation.js server.js

Ao fazer requisições para http://localhost:3000/api/status, você verá os logs de telemetria aparecendo no seu console, mostrando o tempo de execução (span) e métricas de requisições HTTP.

Visualizando os Dados e Criando Dashboards

Ver dados no console é útil para debug, mas insustentável para o dia a dia. Para visualizar esses dados, você precisa de um backend.

Coleta: Use o Prometheus para coletar e armazenar as métricas num banco de dados de séries temporais.
Visualização: Configure o Grafana para ler o Prometheus e criar gráficos bonitos.

Criando Alertas Inteligentes

Não adianta monitorar sem agir. Um bom sistema de alertas deve ser baseado em limites (thresholds) definidos pelos seus SLOs (Service Level Objectives).

Ruim: "Me avise se o servidor cair."
Bom: "Me avise se a taxa de erro for maior que 0.5% durante 5 minutos."

Isso evita fadiga de alertas e garante que a equipe só seja acionada quando realmente importa.

Conclusão

Implementar observabilidade não é uma tarefa única, mas um processo contínuo de melhoria. Começar com o básico — logs estruturados e métricas de latência — já coloca você à frente de muitos desenvolvedores.

Lembre-se de que a ferramenta é apenas uma parte do processo. A cultura de engenharia de confiabilidade (SRE) é o que transforma dados em estabilidade. Se você busca uma plataforma para organizar sua carreira e compartilhar seu conhecimento técnico com o mercado, o Downfor é o lugar ideal para construir sua presença digital.

Comece pequeno, meça tudo e evolua continuamente. Sua API (e seus usuários) agradecerão.