Como implementar OpenTelemetry em microserviços: guia prático para produção

Microserviços tornam a entrega de software mais independente, mas também tornam os incidentes mais difíceis de investigar. Uma única requisição pode atravessar gateway, APIs, filas, cache, banco de dados e provedores externos. Quando cada componente registra informações isoladas, descobrir a causa raiz vira uma busca lenta e imprecisa.

O OpenTelemetry em microserviços oferece uma forma padronizada de gerar, transportar e exportar telemetria. Neste guia, você verá como estruturar traces, métricas e logs correlacionados para operar em produção com mais contexto, controle e previsibilidade.

Por que OpenTelemetry é essencial para microserviços em produção

Monitoramento responde rapidamente se um indicador está fora do esperado; observabilidade ajuda a explicar por que isso aconteceu. Em sistemas distribuídos, essa distinção é decisiva: uma elevação de latência no gateway pode ter origem em uma consulta lenta, uma fila congestionada ou uma dependência externa.

Traces mostram o caminho de uma operação entre serviços. Métricas revelam tendências, capacidade e sintomas recorrentes. Logs registram detalhes técnicos e eventos. Quando esses sinais compartilham contexto, a equipe deixa de comparar telas desconectadas e passa a seguir uma jornada completa.

Imagine um pedido que passa por catálogo, estoque, pagamento e notificação. Um trace distribuído mostra onde o tempo foi consumido e qual dependência falhou. Essa visão reduz o tempo de diagnóstico e ajuda a priorizar correções com base em evidências.

Entenda a arquitetura do OpenTelemetry antes de instrumentar

A arquitetura começa na aplicação. APIs, SDKs e bibliotecas de instrumentação automática capturam telemetria de frameworks, clientes HTTP, bancos de dados e mensageria. Para operações de negócio relevantes, o time pode criar spans manuais.

Em seguida, exporters enviam os dados, normalmente pelo protocolo OTLP, para o OpenTelemetry Collector. O Collector funciona como uma camada independente entre aplicações e destinos: recebe sinais, processa dados e os encaminha ao backend de observabilidade escolhido.

Essa separação permite evoluir a arquitetura de observabilidade sem acoplar o código de cada serviço a um fornecedor específico. Também centraliza políticas de filtragem, enriquecimento e controle de envio.

O backend, por sua vez, armazena e consulta os sinais. A aplicação deve continuar responsável por gerar telemetria útil; o Collector deve aplicar controles operacionais; e o backend deve permitir investigação, alertas e visualizações.

Defina convenções de telemetria e atributos antes do código

Instrumentar sem convenções produz dados difíceis de consultar. Antes de adicionar dependências, defina um catálogo mínimo de atributos de recurso: service.name, service.version, deployment.environment e, quando fizer sentido, região ou zona.

Use nomes estáveis para serviços e operações. Um serviço chamado pagamento-api deve manter esse identificador em traces, métricas e logs. Para spans, prefira nomes orientados à operação, como POST /payments ou payment.authorize, evitando identificadores dinâmicos.

Inclua atributos de negócio apenas quando ajudarem na investigação e não expuserem informações pessoais, segredos, tokens ou payloads completos. Também evite alta cardinalidade: IDs de usuário, IDs de pedido e valores arbitrários como labels de métricas aumentam custo e reduzem a utilidade das consultas.

Documente essas decisões como parte do padrão de engenharia. Assim, novos serviços nascem com telemetria compatível e os painéis permanecem confiáveis ao longo do tempo.

Instrumente serviços e propague o contexto distribuído

Comece pela instrumentação automática. Ela costuma cobrir rapidamente o servidor HTTP, clientes HTTP, acesso a banco, chamadas gRPC e bibliotecas de mensageria. Valide primeiro uma jornada crítica em ambiente de homologação antes de ampliar a cobertura.

Crie spans manuais somente onde houver uma etapa de negócio que não apareça naturalmente na instrumentação, como cálculo de frete, validação antifraude ou composição de uma resposta. Spans em excesso criam ruído; o objetivo é registrar fronteiras e decisões importantes.

A propagação de contexto é o ponto que mantém o trace unido. Em chamadas HTTP e gRPC, o cliente deve injetar o contexto nos headers e o serviço receptor deve extraí-lo. Em filas e tópicos, publique o contexto nos cabeçalhos da mensagem e extraia-o no consumidor antes de iniciar o processamento.

requisição HTTP → gateway → serviço A → fila
                         └→ contexto do trace nos headers
fila → serviço B → extrai contexto → continua o mesmo trace

Registre exceções e códigos de erro nos spans de forma consistente. Um erro tratado pode ser relevante para a operação, mas não deve necessariamente marcar toda a requisição como falha. Preserve essa semântica para que alertas e análises não sejam distorcidos.

Configure o OpenTelemetry Collector para produção

Em produção, o Collector deve ser tratado como uma camada de controle da telemetria. Ele é composto, em linhas gerais, por receivers, processors, exporters e pipelines. Receivers recebem dados; processors aplicam regras; exporters enviam os sinais aos destinos.

Prefira OTLP entre aplicações e Collector. Em cada pipeline, aplique ao menos batch e limites de memória para reduzir overhead e evitar pressão descontrolada sobre o processo. Adicione atributos de ambiente de forma centralizada quando essa informação for confiável fora da aplicação.

Filtros devem remover atributos proibidos antes da exportação. Configure retentativas e filas conforme a criticidade e a capacidade do destino, mas monitore o próprio Collector: filas acumuladas, recusas e erros de exportação indicam perda potencial de visibilidade.

Para cenários mais resilientes, alinhe o desenho do Collector às estratégias de alta disponibilidade adotadas pela plataforma. Separe pipelines de traces, métricas e logs quando os requisitos de retenção, filtragem ou destino forem diferentes.

Correlacione traces, métricas e logs para investigar incidentes

A correlação transforma sinais em uma rotina operacional objetiva. Comece por uma métrica ou alerta: aumento de latência, taxa de erro, saturação ou consumo de fila. Em seguida, filtre os traces do endpoint e período afetados para encontrar a dependência ou operação que degradou.

Quando o trace apontar um span problemático, navegue até os logs daquele serviço usando trace_id e span_id. Os logs devem trazer o detalhe necessário para entender o erro — por exemplo, timeout, tipo de exceção ou estado da integração — sem carregar dados sensíveis.

Um fluxo típico é: alerta de latência no endpoint de pagamento, trace com atraso em uma consulta e log correlacionado confirmando timeout de conexão. A equipe obtém uma hipótese verificável sem depender de tentativa e erro.

Essa prática também torna SLOs mais úteis. Métricas indicam quando o objetivo de confiabilidade foi ameaçado; traces e logs explicam o impacto e orientam a resposta.

Controle custo, desempenho e segurança da telemetria

Telemetria precisa de um orçamento. O volume de spans, logs e séries de métricas cresce rapidamente em sistemas de alto tráfego. Meça o impacto da instrumentação em CPU, memória, rede e armazenamento antes de padronizar configurações para todos os serviços.

Sampling é o principal mecanismo de controle para traces. Uma política prática pode reter todos os traces com erro e uma amostra dos traces saudáveis, ajustando a taxa por ambiente e criticidade. Quando disponível, o sampling baseado em cauda ajuda a preservar jornadas lentas ou com falha, mas exige capacidade adicional no pipeline.

Controle cardinalidade desde a origem. Não use valores únicos ou quase únicos como dimensões de métricas. Defina retenção adequada por sinal e ambiente, e remova segredos, tokens, dados pessoais e corpos de requisição desnecessários antes que deixem a aplicação.

Revise periodicamente o que é coletado. O melhor dado de observabilidade é aquele que responde a uma pergunta operacional real com custo e risco proporcionais.

Checklist de rollout do OpenTelemetry em produção

Uma adoção incremental é mais segura do que instrumentar todo o ecossistema de uma vez. Priorize fluxos críticos, valide a qualidade dos dados e replique um padrão comprovado.

• Mapeie jornadas prioritárias, dependências e responsáveis pelos serviços.
• Defina atributos de recurso, nomes de spans e política de dados sensíveis.
• Habilite instrumentação automática e acrescente spans manuais apenas quando necessário.
• Valide propagação de contexto em HTTP, gRPC, filas e tarefas assíncronas.
• Configure o Collector com batch, limites de memória, filtros e monitoramento próprio.
• Garanta que logs estruturados incluam identificadores de trace e span.
• Crie alertas e painéis para os sintomas mais relevantes do negócio e da plataforma.
• Revise sampling, cardinalidade, retenção e cobertura de instrumentação regularmente.

Comece, por exemplo, por autenticação e pagamento. Após observar a jornada completa por algumas semanas, corrija lacunas de nomenclatura, correlação e custo antes de levar o padrão aos demais domínios. Essa evolução contínua é a base da maturidade de observabilidade.

Conclusão

Implementar OpenTelemetry não é apenas instalar um SDK. É criar um contrato operacional para que serviços, equipes e ferramentas compartilhem o mesmo contexto durante uma investigação.

Com convenções claras, propagação de contexto, Collector bem configurado e correlação entre traces, métricas e logs, incidentes deixam de ser uma coleção de sinais dispersos. A operação ganha um caminho reproduzível para detectar, explicar e resolver problemas distribuídos.

Quer implementar observabilidade ponta a ponta nos seus microserviços? Fale com a Max Alex para estruturar uma estratégia de OpenTelemetry, monitoramento e confiabilidade alinhada aos objetivos do seu negócio.