OpenTelemetry: como monitorar logs, métricas e traces em aplicações

O que é OpenTelemetry?

OpenTelemetry, também chamado de OTel, é um framework aberto e independente de fornecedor para instrumentar, gerar, coletar e exportar telemetria.

Ele reúne especificações, APIs, SDKs, bibliotecas de instrumentação, convenções semânticas, o protocolo OTLP e o OpenTelemetry Collector.

A documentação oficial do OpenTelemetry apresenta traces, métricas e logs como os principais sinais do projeto. A proposta é permitir que aplicações produzam esses dados em um formato consistente e os enviem a diferentes ferramentas de análise sem reescrever toda a instrumentação.

Esse padrão é valioso em arquiteturas com muitos componentes, nas quais uma mesma operação atravessa fronteiras de processo e rede.

Nosso conteúdo sobre microsserviços para iniciantes explica por que essa distribuição traz flexibilidade, mas também torna as falhas mais difíceis de localizar.

OpenTelemetry não é uma plataforma de monitoramento

O OpenTelemetry produz e movimenta telemetria, mas não é, por si só, a interface em que a equipe consulta painéis, cria alertas e investiga dados históricos.

Para isso, ainda é necessário um backend de observabilidade, seja ele um conjunto de ferramentas abertas, um serviço gerenciado ou uma plataforma comercial.

Essa separação reduz dependência de fornecedor. A aplicação pode exportar sinais pelo mesmo protocolo para destinos diferentes, enquanto o Collector centraliza transformação, filtragem e roteamento.

Para compreender a camada de análise e alertas, leia também o artigo sobre observabilidade e monitoramento.

Os três sinais de observabilidade

Logs, métricas e traces não são três versões da mesma informação. Cada sinal responde melhor a um tipo de pergunta.

O ganho aparece quando eles compartilham contexto suficiente para que a investigação passe de um sintoma agregado para uma requisição e, então, para o evento que explica a falha.

Traces

Um trace representa a jornada de uma operação. Cada etapa é registrada como um span, com início, duração, atributos, eventos e estado.

Uma requisição pode ter spans para a rota HTTP, consulta ao banco, chamada a outro serviço e publicação em uma fila. A relação entre pai e filho ajuda a localizar onde o tempo foi gasto ou o erro ocorreu.

Métricas

Métricas são valores agregáveis ao longo do tempo, como quantidade de requisições, duração, uso de memória, tamanho da fila e taxa de erros.

Elas são eficientes para painéis e alertas porque resumem o comportamento do sistema. Uma métrica mostra que existe um problema; um trace pode revelar uma ocorrência concreta desse problema.

Logs

Logs registram eventos discretos, geralmente com mensagem, horário, severidade e campos estruturados.

Eles continuam úteis para detalhes de negócio e diagnóstico, mas precisam de contexto.

Quando um log inclui o identificador do trace e do span ativos, a equipe consegue sair da visualização distribuída e chegar ao evento correspondente sem procurar manualmente por horário.

Como funciona a arquitetura

1. Instrumentação: código automático ou manual cria spans, métricas e registros.
2. API: define como o código da aplicação interage com a telemetria.
3. SDK: amostra, processa e prepara os sinais para exportação.
4. Exportador: envia os dados, normalmente por OTLP.
5. Collector: recebe, processa e encaminha a telemetria.
6. Backend: armazena, consulta, visualiza e gera alertas.

O OpenTelemetry Protocol, ou OTLP, define a codificação e o transporte entre fontes, componentes intermediários e backends.

Os transportes mais comuns usam gRPC ou HTTP. Assim, a aplicação pode apontar para um endpoint padronizado em vez de integrar diretamente cada destino.

Instrumentação automática e manual

A instrumentação automática reconhece frameworks e bibliotecas conhecidas para criar telemetria sem alterar cada trecho da aplicação.

Em Node.js, ela pode observar o servidor HTTP, rotas Express, clientes de banco e outras dependências compatíveis. É a forma mais rápida de obter uma visão inicial.

Porém, uma biblioteca enxerga operações técnicas, não necessariamente a intenção do produto. Ela sabe que houve uma consulta SQL, mas não que o sistema estava reservando estoque ou calculando frete.

A instrumentação manual adiciona spans e atributos nesses pontos de negócio. Uma implementação madura combina as duas abordagens.

Como instrumentar uma aplicação Node.js

O exemplo usa instrumentação automática e exportação OTLP. Confirme as versões e os pacotes atuais no guia oficial para Node.js, pois a implementação de cada linguagem evolui de forma independente.

npm install @opentelemetry/api
npm install --save-dev @opentelemetry/auto-instrumentations-node

Em seguida, inicie a aplicação carregando o registro de autoinstrumentação antes do código principal. O endpoint abaixo considera um Collector local recebendo OTLP por HTTP:

OTEL_SERVICE_NAME=checkout-api \
OTEL_TRACES_EXPORTER=otlp \
OTEL_METRICS_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register" \
node app.js

O nome do serviço precisa ser estável e descritivo. Evite nomes que mudam a cada implantação ou réplica.

Se sua base ainda está sendo estruturada, o artigo sobre Node.js para back-end ajuda a entender onde esse código se encaixa.

Adicionar spans de negócio

Crie spans manuais somente em operações que ajudem a explicar o comportamento do sistema.

O exemplo registra a região de entrega, captura exceções e garante o encerramento do span:

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('checkout');

export async function calcularFrete(pedido) {
  return tracer.startActiveSpan('calcular-frete', async (span) => {
    try {
      span.setAttribute('shipping.region', pedido.regiao);
      return await servicoDeFrete.calcular(pedido);
    } catch (erro) {
      span.recordException(erro);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw erro;
    } finally {
      span.end();
    }
  });
}

Não registre corpo completo de requisições, senhas, tokens ou dados pessoais como atributos.

Também evite valores de cardinalidade praticamente ilimitada, como um identificador diferente para cada usuário em métricas, pois isso pode aumentar drasticamente armazenamento e processamento.

O papel do OpenTelemetry Collector

O Collector é um serviço independente de fornecedor que recebe, processa e exporta telemetria. Sua arquitetura é formada principalmente por receivers, processors e exporters.

Receivers aceitam os dados; processors podem agrupar, limitar memória, remover campos ou enriquecer atributos; exporters enviam o resultado aos backends.

Colocar o Collector entre aplicações e destinos reduz credenciais espalhadas, oferece controle central e permite trocar ou adicionar backends sem alterar todos os serviços.

Ele também pode proteger a aplicação de instabilidades momentâneas na exportação, embora filas, memória e comportamento de retry devam ser configurados e monitorados.

Exemplo de configuração do Collector

A configuração a seguir recebe os três sinais por OTLP, aplica proteção de memória e processamento em lote e imprime dados para validação local.

Consulte a documentação de configuração do Collector antes de adaptar para produção.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
  batch: {}

exporters:
  debug:
    verbosity: basic

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [debug]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [debug]

O exporter debug é útil para desenvolvimento, não como armazenamento. Em produção, configure o exporter do destino, autenticação, TLS, filas e limites adequados.

Valide a sintaxe com a mesma distribuição e versão do Collector que será implantada.

Como correlacionar logs, métricas e traces

Imagine um alerta de aumento na duração p95 de uma API. Uma métrica com exemplar pode apontar para um trace representativo.

Esse trace mostra que o tempo está concentrado em uma chamada ao serviço de pagamento.

Ao abrir o span, o identificador correlacionado leva aos logs emitidos durante aquela chamada e revela uma resposta intermitente do provedor.

Essa navegação depende de propagação de contexto entre serviços. Em HTTP, cabeçalhos transportam os identificadores necessários para continuar o trace. Filas e tarefas assíncronas também precisam propagar o contexto de forma compatível.

Em uma API REST, a autoinstrumentação costuma cuidar dos frameworks suportados, mas integrações próprias devem ser testadas.

Contexto, atributos e convenções semânticas

Dois serviços só podem ser consultados de maneira uniforme se descrevem a mesma coisa com nomes compatíveis.

As convenções semânticas do OpenTelemetry padronizam atributos para HTTP, bancos, mensageria, recursos de nuvem e outros domínios.

Prefira essas convenções antes de criar campos próprios.

• Resource: descreve a entidade que produz telemetria, como serviço, versão e ambiente.
• Trace context: conecta spans da mesma operação.
• Baggage: transporta pares de chave e valor pelo fluxo, exigindo cuidado adicional.
• Attributes: qualificam spans, métricas e logs para consulta.
• Events: marcam ocorrências relevantes dentro de um span.

Defina uma pequena taxonomia interna para nomes de serviço, ambiente, versão e região. Sem governança, a mesma aplicação aparece com variações e fragmenta painéis.

Em pipelines automatizados, trate essas configurações como código; o guia de infraestrutura como código mostra os princípios dessa prática.

Sampling e controle de custos

Registrar todos os traces pode ser desnecessário ou caro em sistemas de alto volume. Sampling escolhe quais traces serão mantidos.

A decisão na origem reduz geração e tráfego; uma decisão posterior, no Collector, consegue considerar o resultado completo e preservar, por exemplo, operações com erro ou latência alta.

Não comece escolhendo uma porcentagem por intuição. Calcule volume, tamanho médio, retenção e orçamento.

Preserve uma referência suficiente para incidentes raros, rotas críticas e diferentes clientes ou regiões, sem usar atributos sensíveis.

A política precisa ser documentada porque amostragem altera o que a equipe consegue investigar.

Segurança e dados sensíveis

• Use TLS e autenticação entre aplicações, Collector e backends.
• Não registre tokens, cookies, senhas ou conteúdo confidencial.
• Remova ou transforme campos no ponto mais próximo da origem.
• Limite quem pode consultar e exportar a telemetria.
• Defina retenção de acordo com necessidade e legislação.
• Proteja o endpoint OTLP contra ingestão não autorizada.

Telemetria pode conter rotas, consultas, identificadores e detalhes da infraestrutura.

Ela deve ser tratada como dado operacional sensível. Processors no Collector ajudam a filtrar atributos, mas não corrigem toda exposição: dados desnecessários não deveriam ser produzidos pela aplicação.

Como implantar o Collector

No padrão de agente, um Collector fica próximo das aplicações e recebe telemetria local.

No padrão de gateway, um conjunto centralizado recebe dados de vários agentes ou serviços, aplica políticas comuns e exporta para os destinos.

É possível combinar os dois modelos.

A escolha depende de rede, isolamento, escala e responsabilidade das equipes.

Em contêineres, o Collector pode ser implantado como serviço lateral, daemon por nó ou gateway. Se o conceito ainda for novo, veja as diferenças entre Docker e máquinas virtuais.

Em qualquer formato, monitore o próprio Collector: filas cheias, descartes, falhas de exportação, memória e CPU podem criar pontos cegos.

Erros comuns na implementação

• Coletar tudo sem pergunta: gera volume, mas não melhora decisões.
• Usar nomes de serviço inconsistentes: fragmenta consultas e painéis.
• Adicionar atributos de alta cardinalidade às métricas: eleva custo e degrada o backend.
• Esquecer propagação em filas: quebra traces em operações assíncronas.
• Instrumentar apenas infraestrutura: mostra CPU, mas não a jornada do usuário.
• Exportar diretamente de todos os serviços: espalha configuração e credenciais.
• Ignorar falhas do Collector: cria uma falsa sensação de cobertura.
• Não validar após deploy: um pacote instalado não garante telemetria útil.

Checklist para começar

1. Escolha uma aplicação importante, mas com risco controlado.
2. Defina duas ou três perguntas operacionais que a telemetria deve responder.
3. Padronize nome do serviço, versão e ambiente.
4. Ative instrumentação automática e valide os traces básicos.
5. Adicione spans somente nas operações de negócio relevantes.
6. Envie OTLP para um Collector de teste.
7. Remova dados sensíveis e atributos de cardinalidade excessiva.
8. Conecte o backend e teste a correlação entre os sinais.
9. Crie alertas ligados a impacto real no usuário.
10. Meça overhead, volume, descartes e custo antes de expandir.

Perguntas frequentes

OpenTelemetry substitui Prometheus e Grafana?

Não diretamente. OpenTelemetry padroniza geração, coleta e transporte de telemetria.

Prometheus, Grafana e outras ferramentas podem atuar no armazenamento, consulta, visualização ou alertas.

Elas podem compor a mesma arquitetura.

É obrigatório usar o Collector?

Não. SDKs podem exportar diretamente para um backend compatível. Porém, o Collector é recomendado em muitos ambientes de produção porque centraliza processamento, credenciais, retries, filtragem e roteamento.

OpenTelemetry prejudica o desempenho?

Toda instrumentação possui algum custo. Autoinstrumentação, quantidade de spans, atributos, exportação e sampling influenciam o overhead.

Meça latência, CPU e memória na sua carga real e ajuste a coleta em vez de assumir impacto zero.

É possível começar somente com traces?

Sim. Traces costumam produzir valor rápido em sistemas distribuídos. Depois, a equipe pode integrar métricas e logs com uma taxonomia consistente.

É melhor ter um sinal bem implementado do que três sinais ruidosos.

OpenTelemetry funciona em monólitos?

Sim. Ele pode revelar rotas lentas, consultas demoradas, integrações externas e operações de negócio dentro de um monólito.

A utilidade não depende de microsserviços, embora a propagação distribuída seja um caso de uso importante.

O que é OTLP?

OTLP é o protocolo do OpenTelemetry para transportar dados de telemetria entre fontes, Collectors e backends.

Ele possui especificações para traces, métricas e logs e pode operar sobre gRPC ou HTTP.

Conclusão

OpenTelemetry oferece uma base comum para observar aplicações sem acoplar cada serviço a uma plataforma específica.

APIs e SDKs geram os sinais, OTLP os transporta, o Collector processa e roteia, e o backend transforma telemetria em consultas, painéis e alertas.

A adoção mais saudável começa pequena: uma aplicação, perguntas operacionais claras, instrumentação automática, alguns spans de negócio e um Collector monitorado.

Correlação, governança de atributos, sampling e proteção de dados importam mais do que simplesmente aumentar o volume coletado. Telemetria só cria valor quando reduz o tempo entre perceber um sintoma e compreender sua causa.