OpenTelemetry no Node.js: Guia Prático

Aplicações Node.js modernas dependem de APIs, bancos de dados, filas, caches e serviços externos. Quando algo fica lento ou apresenta erro, olhar apenas os logs nem sempre é suficiente. O OpenTelemetry no Node.js padroniza a coleta de traces, métricas e logs, permitindo acompanhar uma requisição do início ao fim, mesmo quando ela atravessa vários serviços.

Neste guia, você aprenderá a instrumentar uma API Node.js, exportar telemetria por OTLP, criar spans personalizados, adicionar atributos úteis e evitar erros comuns em produção. Antes de começar, vale revisar o que é Node.js, entender o que é uma API e conhecer o processo de criação de APIs com Node.js.

O que é OpenTelemetry?

OpenTelemetry é um projeto aberto da Cloud Native Computing Foundation que fornece APIs, SDKs, convenções semânticas e protocolos para observabilidade. Ele não é uma plataforma completa de monitoramento. Em vez disso, coleta e transporta dados para ferramentas como Jaeger, Grafana Tempo, Prometheus, Elastic e outros backends compatíveis.

Os três pilares principais são traces, métricas e logs. Traces mostram o caminho de uma operação entre serviços. Métricas representam valores agregados, como latência, uso de memória e quantidade de erros. Logs registram eventos detalhados e podem ser correlacionados com os traces.

A vantagem é reduzir a dependência de um fornecedor. A aplicação adota um padrão comum e pode trocar o destino dos dados com menos alterações.

Por que usar OpenTelemetry no Node.js?

Uma API pode responder lentamente por muitos motivos: consulta SQL sem índice, serviço externo indisponível, fila congestionada, cache ineficiente ou processamento excessivo. Um trace divide a duração total em etapas menores e mostra onde o tempo foi gasto.

Com uma boa instrumentação, você consegue descobrir qual endpoint apresenta maior latência, qual consulta está atrasando a resposta, qual dependência falha com mais frequência e quanto tempo uma mensagem permanece na fila. Esse contexto complementa técnicas de otimização de APIs RESTful em Node.js e o uso de cache e filas com Redis.

Preparando o projeto

Crie uma aplicação Express e instale os pacotes básicos:

mkdir api-observavel
cd api-observavel
npm init -y
npm install express
npm install @opentelemetry/api @opentelemetry/sdk-node
npm install @opentelemetry/auto-instrumentations-node
npm install @opentelemetry/exporter-trace-otlp-http

Crie uma rota simples:

const express = require('express');
const app = express();

app.get('/produtos/:id', async (req, res) => {
  await new Promise(resolve => setTimeout(resolve, 120));
  res.json({ id: req.params.id, nome: 'Teclado' });
});

app.listen(3000);

Nesse momento, a API funciona, mas ainda não envia telemetria.

Configurando o SDK

Crie um arquivo chamado telemetry.js:

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require(
  '@opentelemetry/auto-instrumentations-node'
);
const { OTLPTraceExporter } = require(
  '@opentelemetry/exporter-trace-otlp-http'
);

const exporter = new OTLPTraceExporter({
  url: 'http://localhost:4318/v1/traces'
});

const sdk = new NodeSDK({
  traceExporter: exporter,
  instrumentations: [getNodeAutoInstrumentations()]
});

sdk.start();

Carregue a instrumentação antes da aplicação:

node --require ./telemetry.js server.js

A ordem é importante. O SDK deve ser inicializado antes do Express, do cliente HTTP e dos drivers de banco. Caso contrário, os módulos podem ser carregados sem os hooks necessários.

Instrumentação automática

O pacote de auto-instrumentação ativa integrações para módulos populares. Ele pode capturar requisições HTTP, rotas do Express, consultas a bancos e chamadas a serviços externos. Os spans gerados normalmente incluem método HTTP, rota, código de status, duração e erros.

Essa automação acelera o início, mas não entende todas as regras do negócio. Para medir operações importantes, crie spans personalizados.

Criando spans personalizados

const { trace } = require('@opentelemetry/api');
const tracer = trace.getTracer('catalogo-service');

async function buscarProduto(id) {
  return tracer.startActiveSpan('buscar-produto', async span => {
    try {
      span.setAttribute('produto.id', id);
      await new Promise(resolve => setTimeout(resolve, 80));
      return { id, nome: 'Teclado' };
    } catch (error) {
      span.recordException(error);
      span.setStatus({ code: 2, message: error.message });
      throw error;
    } finally {
      span.end();
    }
  });
}

O bloco finally garante o encerramento do span mesmo quando ocorre uma exceção. Spans abertos por tempo indefinido geram traces incompletos e podem aumentar o consumo de memória.

Atributos úteis e segurança

Atributos tornam os traces pesquisáveis. Bons exemplos incluem versão da aplicação, ambiente, tipo de operação, resultado do cache e nome do serviço. Evite guardar senhas, tokens, documentos, conteúdo completo de requisições ou informações pessoais.

Também evite valores com cardinalidade muito alta. Um atributo que recebe milhões de IDs diferentes aumenta custos e dificulta consultas. Prefira dados técnicos agregáveis e use identificadores detalhados apenas quando houver necessidade real e política de retenção adequada.

Nome e versão do serviço

Em sistemas distribuídos, cada span deve indicar claramente qual serviço o gerou. Configure variáveis de ambiente:

OTEL_SERVICE_NAME=catalogo-api
OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.0,deployment.environment=production

O nome deve ser estável. Não inclua IDs aleatórios ou nomes de contêiner no nome principal. Informações de instância podem ficar em atributos separados.

Exportando para o Collector

Em produção, envie os dados para o OpenTelemetry Collector. Ele recebe telemetria, aplica filtros, processamento e amostragem, e encaminha para um ou mais destinos.

O fluxo costuma ser: aplicação Node.js, Collector e backend de observabilidade. Essa arquitetura reduz configurações dentro da aplicação e facilita trocar o destino. Consulte a documentação oficial do OpenTelemetry para JavaScript e as instrumentações JavaScript mantidas pela comunidade.

Amostragem de traces

Guardar todos os traces pode ser caro em aplicações com grande volume. A amostragem define quais requisições serão exportadas. Em desenvolvimento, capturar tudo é útil. Em produção, uma porcentagem pode ser suficiente.

Uma estratégia equilibrada mantém todos os erros e apenas uma parte das requisições bem-sucedidas. O Collector também pode usar amostragem posterior, analisando o trace completo antes de decidir se ele deve ser armazenado. Não reduza demais a taxa, pois incidentes raros podem desaparecer.

Correlacionando logs e traces

Inclua trace_id e span_id nos logs estruturados. Ao encontrar um erro, você poderá abrir o trace correspondente e visualizar banco, cache, serviços externos e duração de cada etapa.

const span = trace.getActiveSpan();
const context = span?.spanContext();

console.log(JSON.stringify({
  level: 'info',
  message: 'Produto carregado',
  trace_id: context?.traceId,
  span_id: context?.spanId
}));

Essa correlação reduz o tempo de investigação e evita procurar manualmente eventos espalhados em diferentes serviços.

Métricas importantes

Além de traces, acompanhe requisições por segundo, latência nos percentis p50, p95 e p99, taxa de erros por rota, uso de CPU e memória, tempo de dependências e tamanho de filas.

Médias podem esconder problemas. Uma média de 200 ms pode parecer boa mesmo quando uma parcela dos usuários espera vários segundos. Percentis mostram melhor a experiência nas requisições mais lentas.

Tratando erros

Registre exceções e defina o status do span quando a operação realmente falhar. Uma resposta 404 pode ser normal em um endpoint de busca, enquanto uma resposta 200 com dados inválidos pode representar erro de negócio. A classificação deve refletir o comportamento esperado da aplicação.

Evite colocar detalhes sensíveis na mensagem do erro. Padronize categorias para facilitar filtros, painéis e alertas.

Impacto no desempenho

Observabilidade consome recursos. Instrumentações excessivas, atributos grandes e exportação síncrona podem aumentar a latência. Use processamento em lote, limites de fila e monitore o próprio pipeline de telemetria.

Não crie spans para cada operação trivial dentro de loops grandes. Meça a operação como um todo e adicione eventos apenas para etapas relevantes. Faça testes de carga antes de liberar em produção.

Erros comuns

• Carregar a instrumentação depois da aplicação.
• Usar nomes de spans com IDs e URLs completas.
• Exportar dados pessoais ou segredos.
• Não encerrar o SDK corretamente.
• Capturar todos os traces sem avaliar custos.
• Não monitorar a saúde do Collector.
• Depender somente de traces e ignorar métricas e logs.

Checklist para produção

• Inicialize o SDK antes dos módulos instrumentados.
• Configure nome, versão e ambiente do serviço.
• Use OTLP e um Collector sempre que possível.
• Remova dados pessoais e segredos.
• Defina uma política de amostragem.
• Correlacione logs com trace e span IDs.
• Monitore erros e percentis de latência.
• Teste o impacto de desempenho.

Conclusão

Adotar OpenTelemetry no Node.js oferece uma visão completa do comportamento de APIs e serviços. A instrumentação automática acelera o início, enquanto spans personalizados revelam operações específicas do negócio. Com atributos bem escolhidos, correlação de logs e exportação por OTLP, investigar lentidão e falhas deixa de depender de suposições.

Comece com uma API pequena, configure um Collector e acompanhe rotas críticas. Depois, expanda para banco, cache, filas e serviços externos. O objetivo não é coletar o máximo de dados possível, mas obter informação suficiente para detectar, explicar e resolver problemas com rapidez.