OpenTelemetry: o que é, como funciona e como implementar

Durante anos, instrumentar uma aplicação para observabilidade significava escolher um fornecedor e aceitar o lock-in. O agente de APM do fornecedor A não conversava com o backend do fornecedor B. Migrar de plataforma exigia reescrever toda a instrumentação. Times que usavam múltiplas linguagens tinham múltiplos padrões incompatíveis de coleta de dados.

O OpenTelemetry foi criado para resolver esse problema de forma definitiva. É um projeto open source mantido pela CNCF (Cloud Native Computing Foundation) que define um padrão único e agnóstico de vendor para instrumentar aplicações e exportar dados de telemetria — métricas, logs e traces — para qualquer backend de observabilidade.

Neste guia técnico, você vai entender o que é OpenTelemetry, como funciona sua arquitetura, quais são os componentes principais e como implementar em projetos reais.

O que é OpenTelemetry?

OpenTelemetry (abreviado OTel) é um framework open source de observabilidade que fornece APIs, SDKs, agentes e um protocolo de exportação padronizados para coletar dados de telemetria de aplicações e infraestrutura. O projeto nasceu em 2019 da fusão de dois projetos anteriores — OpenTracing e OpenCensus — e se tornou rapidamente o padrão de facto da indústria para instrumentação.

A proposta central é simples: uma aplicação instrumentada com OpenTelemetry pode exportar seus dados para Datadog, Prometheus, Grafana Tempo, Jaeger, Elastic, New Relic ou qualquer outro backend compatível — sem alterar o código de instrumentação. Isso elimina o vendor lock-in e permite que a escolha da plataforma de observabilidade seja independente da estratégia de instrumentação.

O projeto é mantido pela CNCF, a mesma fundação que mantém Kubernetes e Prometheus, e conta com contribuições de Google, Microsoft, AWS, Datadog, New Relic e dezenas de outras empresas. Mais de 40 fabricantes de ferramentas de observabilidade suportam OpenTelemetry nativamente.

Os três pilares do OpenTelemetry

O OpenTelemetry cobre os três tipos de dados de telemetria que compõem a observabilidade moderna.

Traces

O suporte a traces distribuídos foi o primeiro pilar implementado pelo OpenTelemetry, herdado diretamente do OpenTracing. Um trace representa a jornada completa de uma requisição por todos os serviços de um sistema distribuído.

O OTel propaga automaticamente o trace_id — um identificador único — por todos os serviços que a requisição atravessa, via headers HTTP (W3C TraceContext é o padrão), mensagens de fila ou gRPC. Isso permite que os traces de diferentes serviços e linguagens sejam correlacionados em uma única visão coerente no backend de observabilidade.

Métricas

A API de métricas do OpenTelemetry define instrumentos padronizados: Counter (valor que só cresce), Gauge (valor que varia), Histogram (distribuição de valores para percentis) e UpDownCounter. A exportação suporta formatos compatíveis com Prometheus, OTLP e outros backends.

O OpenTelemetry também define convenções semânticas — nomes e atributos padronizados para métricas comuns de serviços HTTP, bancos de dados, mensageria e runtimes. Isso garante que dashboards e alertas sejam reutilizáveis entre serviços e equipes.

Logs

O suporte a logs é o terceiro pilar, adicionado mais recentemente. O OTel não substitui as bibliotecas de logging existentes (Log4j, SLF4J, Winston, etc.) — ele as instrumenta automaticamente para injetar o trace_id e span_id do contexto atual em cada linha de log.

Essa injeção automática é o que viabiliza a correlação entre os três pilares: um alerta de métrica leva ao trace afetado que leva aos logs exatos daquele trace — sem nenhuma busca manual.

Arquitetura do OpenTelemetry

SDK e instrumentação automática

O OpenTelemetry fornece SDKs para todas as principais linguagens: Java, Python, Go, JavaScript/Node.js, .NET, Ruby, PHP, Rust, entre outras. Cada SDK inclui instrumentação automática para as bibliotecas mais populares — frameworks web (Express, Django, Spring), clientes HTTP, drivers de banco de dados — que geram spans, métricas e logs sem necessidade de modificar o código da aplicação.

Para casos específicos, a API permite adicionar instrumentação manual: criar spans customizados, adicionar atributos de contexto de negócio e registrar eventos relevantes para o domínio da aplicação.

OpenTelemetry Collector

O OTel Collector é um componente opcional mas altamente recomendado: um processo separado que recebe dados de telemetria das aplicações, processa (filtra, transforma, agrega) e exporta para um ou múltiplos backends.

A vantagem do Collector é desacoplar as aplicações dos backends de observabilidade: se a organização muda de Datadog para Elastic, só precisa reconfigurar o Collector — as aplicações permanecem inalteradas. Ele também permite adicionar processamento — como sampling de traces ou enriquecimento de atributos — sem alterar código da aplicação.

Protocolo OTLP

O OTLP (OpenTelemetry Protocol) é o protocolo de transporte definido pelo OTel para envio de dados de telemetria. Suporta gRPC e HTTP/Protobuf como transporte. É o formato nativo de exportação do OTel Collector e é suportado diretamente por todos os principais backends de observabilidade.

OpenTelemetry e a correlação entre pilares

O diferencial técnico mais importante do OpenTelemetry é a propagação automática de contexto que viabiliza correlação entre os três pilares. O mecanismo funciona assim: quando uma requisição chega ao serviço, o SDK extrai o trace_id do header, cria um span para aquela operação e armazena o contexto (trace_id + span_id) em um objeto acessível a toda a thread ou coroutine.

Quando a aplicação escreve um log ou registra uma métrica durante o processamento daquela requisição, o SDK injeta automaticamente o trace_id e span_id nos dados. O resultado: logs, métricas e traces da mesma requisição compartilham o mesmo identificador — tornando a navegação entre pilares trivial na plataforma de observabilidade.

Essa correlação é o que permite reduzir o MTTD e o tempo de diagnóstico em incidentes: do alerta de métrica ao trace afetado ao log de erro em segundos, sem busca manual entre ferramentas separadas.

Como implementar OpenTelemetry na prática

A implementação segue quatro etapas em qualquer linguagem.

O primeiro passo é adicionar as dependências do SDK e das instrumentações automáticas ao projeto. Na maioria das linguagens, isso é suficiente para começar a gerar traces e métricas das bibliotecas populares sem alterar o código da aplicação.

O segundo passo é configurar o exportador: para onde os dados serão enviados. Em ambiente de desenvolvimento, o exportador OTLP apontando para um Collector local é o padrão. Em produção, o Collector pode rotear para múltiplos backends.

O terceiro passo é validar a instrumentação automática e adicionar spans customizados para operações de negócio críticas que não são capturadas automaticamente — como chamadas a APIs externas específicas ou operações de domínio relevantes para diagnóstico.

O quarto passo é adotar as convenções semânticas nos atributos customizados, garantindo que os dados gerados pela sua aplicação sejam compatíveis com os dashboards e alertas padronizados da organização.

A referência técnica completa está em opentelemetry.io/docs, que mantém guias de início rápido por linguagem e a especificação completa das convenções semânticas. Para uma visão de como o OTel se encaixa no ecossistema cloud-native, a página do projeto na CNCF contextualiza sua maturidade e adoção.

Conclusão

O OpenTelemetry resolveu o problema de fragmentação de instrumentação que por anos bloqueou a adoção de observabilidade em larga escala. Ao padronizar APIs, SDKs e o protocolo de exportação, ele eliminou o vendor lock-in e tornou possível instrumentar uma aplicação uma vez e exportar para qualquer backend.

Para times de SRE e DevOps, OpenTelemetry é hoje o ponto de partida recomendado para qualquer estratégia de observabilidade: ele une os três pilares — métricas, logs e traces — em um pipeline coeso com correlação automática. Para estruturar sua estratégia de instrumentação e observabilidade com OpenTelemetry, fale com nossos especialistas.