OpenTelemetry em microserviços: erros que geram falhas, lentidão ou retrabalho

Como identificar problemas de instrumentação, propagação de contexto e coleta antes que prejudiquem o diagnóstico e o desempenho da aplicação.

Adotar OpenTelemetry em microserviços pode trazer uma frustração: o time passa a coletar mais dados, mas continua sem explicar por que um pagamento falhou. Ao mesmo tempo, aumentam o consumo de memória, o volume exportado e a manutenção dos painéis.

Esses problemas têm causas diferentes. Um trace incompleto pode indicar perda de contexto, descarte por sampling ou falha de exportação. Já a piora de latência pode estar relacionada ao trabalho acrescentado pela instrumentação. Separar essas hipóteses é o primeiro passo para corrigir o que realmente afeta a operação.

Os exemplos a seguir são cenários ilustrativos. Use-os para investigar um fluxo representativo da sua aplicação e validar cada mudança com evidências.

O problema está na aplicação ou no pipeline de telemetria?

Considere um checkout que chama os serviços de pedidos e pagamentos e publica uma mensagem para processamento posterior. A resposta ao cliente mantém o tempo habitual, mas o trace mostra apenas o serviço de pedidos.

Esse sintoma, sozinho, não comprova indisponibilidade dos demais serviços. Antes de alterar a aplicação, confira a continuidade do contexto, as decisões de amostragem e o caminho de exportação.

A API do OpenTelemetry oferece interfaces de instrumentação. O SDK implementa gravação, processamento e exportação dos sinais. O Collector pode receber, transformar e encaminhar telemetria. Armazenamento, indexação, visualização e consulta dependem do backend e da arquitetura escolhidos.

Duração da requisição e atraso de chegada da telemetria são medidas distintas. Uma operação rápida pode aparecer tarde no backend por causa de lotes ou filas. Registre uma linha de base de latência, erros, throughput, CPU e memória antes das mudanças para não confundir essas situações.

Erro 1: perder o contexto entre serviços, filas e tarefas assíncronas

O tracing distribuído depende de transportar o contexto pelas fronteiras da aplicação. Em uma chamada recebida, a instrumentação extrai o contexto e o torna ativo durante a operação. Na saída, injeta o contexto correspondente no transporte utilizado.

Em HTTP, verifique propagadores compatíveis e a preservação de traceparent e, quando presente, tracestate. Em mensagens, use os metadados suportados pelo transporte. Bibliotecas assíncronas também precisam preservar ou receber explicitamente o contexto.

Imagine que a API publique um evento de pagamento sem contexto nos metadados. O consumidor pode processá-lo corretamente e iniciar um trace isolado. O erro está na continuidade da investigação, embora o pagamento funcione.

Como localizar a fronteira que perde contexto

1. Execute uma requisição controlada e identifique o trace na entrada.
2. Confira o contexto enviado na chamada ou mensagem seguinte, sem registrar credenciais.
3. Verifique o contexto extraído no serviço de destino.
4. Observe se o span de processamento usa a relação esperada.

Em mensageria, nem toda relação precisa formar uma única árvore de spans. Processamento em lote ou relações com múltiplas mensagens podem exigir span links, conforme as convenções e a instrumentação adotadas.

Valide separadamente chamadas diretas, publicação, consumo e execução em segundo plano. Um teste HTTP bem-sucedido não comprova a propagação em toda a arquitetura.

Erro 2: duplicar instrumentação e criar spans sem utilidade

Entre os erros de instrumentação OpenTelemetry, a sobreposição de agentes, integrações automáticas e código manual costuma gerar ruído. Um cliente HTTP já instrumentado recebe um wrapper que cria outro span com os mesmos limites e nenhuma informação adicional.

Antes de remover spans, diferencie duplicação de representação legítima. Um span de servidor e outro de cliente descrevem lados diferentes de uma comunicação. Da mesma forma, uma etapa de negócio pode conter uma consulta ao banco sem representar a mesma operação.

Faça um inventário por serviço: agente instalado, SDK inicializado, bibliotecas instrumentadas e spans manuais. Compare também as informações de escopo de instrumentação disponíveis no backend para identificar quem produziu cada span.

Adicione instrumentação manual quando houver uma pergunta operacional concreta. Por exemplo: quanto tempo a reserva de estoque consome dentro da criação do pedido? Um span nessa etapa pode ajudar mais do que dezenas de spans para funções internas triviais.

• Encerre spans também nos caminhos de exceção e cancelamento.
• Registre falhas conforme as convenções da operação; gravar uma exceção e definir o status do span podem exigir ações distintas.
• Revise inicializações repetidas do SDK e configurações divergentes entre réplicas.
• Confira nomes e atributos antes de expandir a instrumentação.

A evidência de melhoria é um trace que explica o fluxo com menos redundância, preservando as informações necessárias para localizar falhas e espera.

Erro 3: usar atributos sem controle de cardinalidade e padronização

Cardinalidade de métricas é a quantidade de combinações distintas de dimensões. Ao colocar order_id em uma métrica de duração, cada pedido pode criar uma combinação nova. A multiplicação cresce ainda mais quando esse atributo se combina com rota, região e resultado.

Prefira dimensões com valores limitados e úteis para agregação. Para rotas HTTP, use um modelo como /pedidos/{id}, quando fornecido pelo framework, em vez de caminhos como /pedidos/98765. Evite identificadores de usuário, sessão ou pedido nas dimensões de métricas.

Isso não significa que todos os atributos tenham o mesmo custo em todos os sinais. Em traces e logs, identificadores podem ajudar na investigação, desde que sua coleta seja apropriada. Custos de indexação, armazenamento e consulta dependem do backend e de suas políticas.

Padronize a identidade antes de construir painéis

Defina service.name de forma consistente para cada serviço lógico. Registre também versão e ambiente usando atributos compatíveis com as convenções adotadas, como service.version e deployment.environment.name, quando aplicáveis à versão utilizada.

Para organizar essa implantação, consulte o guia de OpenTelemetry em microserviços para produção. Use uma configuração revisável para manter a identidade dos serviços consistente.

Trate mudanças de nomes e atributos como migrações. Liste consultas, painéis e alertas afetados; valide a compatibilidade; e documente a transição. Renomear um atributo sem revisar seus consumidores pode criar retrabalho mesmo quando a coleta continua funcionando.

No exemplo dos pedidos, remova order_id da métrica e mantenha agregações por rota e resultado. Se a investigação individual exigir o identificador, avalie sua presença em spans ou logs, com controle de acesso e retenção adequados.

Erro 4: definir sampling sem considerar erros, latência e topologia

O sampling de traces reduz volume, mas também determina quais evidências estarão disponíveis. No head sampling, a decisão ocorre no início e não conhece o resultado final. Uma estratégia parent-based considera a decisão do contexto pai para manter coerência entre spans.

No tail sampling, o avaliador recebe spans e decide posteriormente, podendo considerar erro ou duração. Ele não recupera spans descartados na origem.

Se o objetivo é investigar pagamentos lentos, descarte agressivo no SDK pode impedir que uma política posterior encontre esses casos. Revise a estratégia completa, da aplicação ao ponto de decisão.

Tail sampling exige capacidade para manter estado e uma janela de decisão. Spans atrasados podem chegar depois dela. Quando houver múltiplos avaliadores, verifique o encaminhamento dos spans de cada trace ao responsável por sua avaliação.

Teste a política com operações normais, lentas e com erro controlado. Confira quais evidências sobreviveram e quanto custaram. Não existe taxa universal adequada para todos os serviços.

Não trate traces amostrados como contagem total de requisições. Use métricas apropriadas para volume e taxas; confirme a origem dessas métricas caso sejam derivadas de spans.

Erro 5: operar o Collector sem limites, filas e recuperação

O OpenTelemetry Collector precisa de capacidade e comportamento de falha definidos. Investigue a entrada verificando endpoint, protocolo OTLP, TLS e autenticação. Depois, confira processamento e exportação.

Uma fila de envio absorve interrupções temporárias dentro de sua capacidade. Retries ajudam diante de falhas transitórias. Filas cheias, erros permanentes e indisponibilidades prolongadas podem resultar em perda. Persistência, quando suportada e configurada, ajuda a preservar a fila durante reinicializações, mas também depende do armazenamento disponível.

Dimensione pela carga e pela recuperação esperada

Estime a entrada de telemetria, a interrupção que precisa tolerar e a capacidade de escoamento após a recuperação. Confira a unidade usada na configuração da fila: itens, requisições ou bytes não são equivalentes.

Defina memória, lotes e tentativas com base nesse cenário. Justifique a ordem dos processors conforme suas dependências e a versão implantada; contenção de memória e transformações que reduzem volume merecem avaliação antes de etapas que acumulam dados.

Em ambiente controlado, interrompa o destino, acompanhe a fila e restabeleça a conexão. Meça ocupação, descartes, recursos e tempo de recuperação. Reinicie também o Collector se sobreviver a reinicializações fizer parte do requisito.

Se o destino não consegue escoar o tráfego normal, aumentar a fila apenas adia a saturação. Corrija o desequilíbrio entre entrada e saída.

Erro 6: medir o overhead apenas depois de instrumentar tudo

Overhead de observabilidade precisa ser medido antes da expansão. Compare o serviço sem instrumentação com a configuração proposta usando carga equivalente, mesma infraestrutura e condições semelhantes de aquecimento.

Separe o custo da aplicação instrumentada do consumo do Collector e do backend. Se compartilham recursos, registre essa condição: a disputa por CPU ou memória pode influenciar o resultado.

1. Execute o cenário de referência e registre sua configuração.
2. Habilite a instrumentação em um serviço ou fluxo delimitado.
3. Compare latência p50, p95 e p99, throughput, erros, CPU e memória.
4. Avalie alocações e coleta de lixo quando forem relevantes ao runtime.
5. Repita com o destino de telemetria indisponível.
6. Confira o encerramento do processo e o comportamento dos buffers.

Os percentis ajudam a observar impactos escondidos pela média. O p99 representa o limite abaixo do qual estão aproximadamente 99% das durações observadas naquela distribuição; ele exige uma amostra representativa para sustentar decisões.

Se o p99 piorar, investigue processamento ou exportação síncrona no caminho da requisição, volume de spans, atributos grandes e contenção de recursos. Exportação em lotes pode reduzir trabalho por envio, mas continua consumindo recursos e precisa de buffers limitados.

Verifique também o desligamento do SDK com prazo compatível com a plataforma. Encerrar o processo antes de escoar dados pendentes pode criar lacunas, enquanto uma espera excessiva pode atrasar a parada do serviço.

Defina critérios de aceite e rollback conforme o orçamento de latência e recursos da aplicação. Expanda somente depois de explicar as diferenças observadas.

Erro 7: coletar dados sensíveis e deixar logs sem correlação

Um log que descreve a falha de pagamento perde utilidade quando não pode ser relacionado à operação correspondente. Ao mesmo tempo, um span que captura um cabeçalho de autorização acrescenta exposição desnecessária.

Verifique a integração do framework de logging com o contexto ativo. Os campos trace_id e span_id precisam ser registrados e interpretados corretamente pelo backend. Confirme o comportamento em uma requisição com erro controlado.

Logs emitidos fora de um contexto ativo podem legitimamente não ter identificadores de trace. A ausência em uma mensagem de inicialização, por exemplo, não comprova falha de instrumentação. Já a ausência durante o processamento de uma requisição merece investigação.

Selecione os dados antes de exportá-los

• Evite captura indiscriminada de corpos, cookies e cabeçalhos de autenticação.
• Revise mensagens de exceção e URLs, que também podem conter informações sensíveis.
• Não transporte credenciais ou dados pessoais em baggage.
• Prefira impedir a coleta na origem e use filtragem como proteção complementar.
• Revise acesso, indexação e retenção conforme a necessidade operacional.

Um identificador em baggage pode atravessar várias chamadas e fronteiras. Antes de propagá-lo, avalie quem o receberá e qual problema ele resolve. Contexto adicional sem finalidade clara aumenta o trabalho de proteção e manutenção.

No exemplo do pagamento, corrija a integração de logs e remova a captura do cabeçalho na origem. Depois, confira os sinais exportados para demonstrar que a correlação funciona e que o dado deixou de ser coletado.

Erro 8: não monitorar o próprio pipeline de observabilidade

Uma queda no número de erros pode representar melhora da aplicação ou interrupção da coleta. Acompanhe entrada, saída, recusas, falhas de envio, ocupação das filas e recursos do Collector para distinguir essas hipóteses.

Entre os nomes documentados estão otelcol_exporter_queue_size, otelcol_exporter_queue_capacity e otelcol_exporter_enqueue_failed_spans. Confira disponibilidade, unidades, dimensões e nomes efetivamente expostos pela versão e pelos componentes utilizados.

Falhas de envio não comprovam, isoladamente, descarte definitivo: tentativas posteriores podem funcionar. Relacione esses eventos ao crescimento da fila, às falhas de enfileiramento e à recuperação da saída.

Ao comparar volumes de entrada e saída, considere filtros, sampling e intervalos de observação. Diferenças podem ser esperadas; uma igualdade simples de contadores não descreve todos os pipelines.

Crie alertas para falhas sustentadas, saturação e reinicializações. Associe cada alerta a um responsável e a um procedimento. Uma sequência útil é conferir conectividade, destino, filas e recursos, antes de alterar a capacidade.

Mantenha uma forma de detectar problemas que não dependa exclusivamente do pipeline afetado. Uma verificação externa ou coleta independente de saúde pode revelar a perda de visibilidade.

Checklist para corrigir os erros e validar o rollout

Comece por exposição de dados e impacto na aplicação. Em seguida, corrija a integridade dos sinais e otimize volume e custos. Essa ordem evita gastar tempo ajustando painéis enquanto a instrumentação prejudica o serviço ou coleta informações desnecessárias.

Valide um fluxo completo antes de ampliar

Selecione a criação e o pagamento de um pedido. Inclua chamada HTTP, consulta ao banco, publicação de evento, consumo assíncrono, erro controlado e indisponibilidade temporária do destino de telemetria.

1. Mapeie responsáveis, versões, bibliotecas, propagadores e configurações.
2. Confirme a continuidade de contexto e as relações esperadas entre spans.
3. Revise duplicações, atributos, identidade dos serviços e sampling.
4. Teste interrupção, recuperação e desligamento dos componentes.
5. Compare desempenho e consumo com a linha de base.
6. Documente critérios de aceite, rollback e revisão após atualizações.

Registre configuração, carga aplicada, resultado observado e decisão tomada. Se uma atualização de biblioteca alterar spans ou atributos, esse registro permitirá identificar o que mudou e quais consumidores precisam de ajuste.

Escolha um fluxo crítico e aplique o checklist: confirme a continuidade dos traces, compare o desempenho e teste a recuperação da coleta. Use os resultados para priorizar as próximas correções e consulte os conteúdos relacionados do blog Max Alex para aprofundar cada etapa.