Prometheus no Node.js: métricas e alertas

Prometheus no Node.js permite expor métricas numéricas para acompanhar tráfego, erros, latência e uso de recursos. O Prometheus coleta essas séries periodicamente e oferece uma linguagem de consulta para alertas e dashboards.

Métricas não substituem logs ou traces. Elas mostram tendências e permitem responder rapidamente se um serviço está saudável, degradado ou próximo da saturação.

Instalando prom-client

npm install prom-client

Métricas padrão

import client from 'prom-client';

client.collectDefaultMetrics({
  prefix: 'app_'
});

As métricas padrão incluem CPU, memória, garbage collection e event loop. Avalie o volume e mantenha nomes consistentes.

Counter

const requests = new client.Counter({
  name: 'http_requests_total',
  help: 'Total de requisições HTTP',
  labelNames: ['method', 'route', 'status_class']
});

Counter só aumenta. Use para requisições, erros, mensagens e retries.

Histogram

const duration = new client.Histogram({
  name: 'http_request_duration_seconds',
  help: 'Duração das requisições HTTP',
  labelNames: ['method', 'route'],
  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2, 5]
});

const end = duration.startTimer({ method: 'GET', route: '/orders/:id' });
try {
  await handleOrder();
} finally {
  end();
}

Defina buckets alinhados ao SLO de latência.

Gauge

const activeJobs = new client.Gauge({
  name: 'jobs_active',
  help: 'Jobs atualmente em execução'
});

Gauge pode subir e descer. É adequado para filas, conexões e tarefas ativas.

Endpoint /metrics

if (req.url === '/metrics') {
  res.setHeader('Content-Type', client.register.contentType);
  res.end(await client.register.metrics());
}

Proteja o endpoint na rede interna ou com autenticação apropriada. Métricas podem revelar detalhes da arquitetura.

Cardinalidade

Nunca use IDs, e-mails, URLs completas ou mensagens de erro como labels. Prefira rota normalizada, método, classe de status e nome lógico da dependência.

Métricas RED

• Rate: requisições por segundo;
• Errors: proporção de falhas;
• Duration: distribuição de latência.

Métricas USE

Para recursos, acompanhe utilização, saturação e erros. Pools de banco, workers e filas devem expor capacidade ativa, espera e rejeições.

Multiprocessos

Em cluster ou múltiplos processos, cada processo mantém seu próprio registro. Prefira coleta por instância ou mecanismo de agregação suportado, evitando somar valores incorretamente.

PromQL

sum(rate(http_requests_total[5m])) by (route)

histogram_quantile(
  0.95,
  sum(rate(http_request_duration_seconds_bucket[5m])) by (le, route)
)

Alertas

Baseie alertas em impacto: taxa de erros, SLO, saturação e ausência de tráfego esperado. Evite alertar apenas porque CPU passou de um valor por poucos segundos.

Exemplars e traces

Alguns pipelines associam exemplars de histogramas a trace IDs. Isso permite abrir um trace representativo a partir de um pico de latência. Consulte Distributed Tracing no Node.js.

Observabilidade da aplicação

Além de HTTP, meça:

• tempo de queries;
• uso do pool;
• mensagens processadas e rejeitadas;
• retries e circuit breaker;
• cache hit ratio;
• event loop lag;
• heap e GC.

Erros comuns

• labels de alta cardinalidade;
• medir apenas CPU;
• buckets inadequados;
• endpoint público;
• contar erros sem total de requisições;
• alertas sem relação com impacto;
• nomes inconsistentes entre serviços.

Conclusão

Prometheus no Node.js oferece métricas eficientes para acompanhar comportamento e capacidade. Comece com RED para serviços, USE para recursos e métricas de negócio realmente acionáveis.

Consulte a documentação de tipos de métricas do Prometheus e o repositório oficial do prom-client.