Skip to main content
Migrar uma plataforma de observabilidade geralmente significa mais do que mudar onde os dados são armazenados. Agentes e SDKs do Datadog talvez já estejam implantados em milhares de aplicações, hosts, máquinas virtuais e pods. Reinstrumentar tudo isso antes mesmo de poder avaliar outro backend transforma a migração em um grande projeto antes que ela gere qualquer valor. O receiver do Datadog integrado à distribuição ClickStack do coletor OpenTelemetry (OTel) elimina esse custo inicial. Seus agentes e SDKs do Datadog continuam funcionando sem alterações. Em vez de enviar dados de telemetria ao Datadog, você os aponta para o receiver, que converte os payloads nativos de logs, traces e métricas do Datadog para o modelo de dados do OpenTelemetry e os encaminha pelo pipeline padrão do coletor até o ClickStack. Como o receiver fica dentro de um pipeline normal do coletor, você pode usá-lo para:
  • Avaliar o ClickStack em conjunto com o Datadog sem mexer no código da aplicação, usando seus agentes atuais para enviar a mesma telemetria para as duas plataformas.
  • Facilitar uma migração, migrando para o ClickStack enquanto mantém sua camada de coleta atual e adota a instrumentação do OpenTelemetry gradualmente.
  • Executar as duas stacks em paralelo no longo prazo, usando cada plataforma naquilo que faz de melhor.

​
Por que executar o ClickStack junto com o Datadog

Para a maioria das equipes, o principal motivo para tirar os dados de observabilidade do Datadog é o custo. Os volumes de logs e traces crescem à medida que as aplicações escalam e mais serviços são instrumentados, o que deixa você com duas opções: gastar mais ou reter menos da telemetria que produz. Esses controles de custo acabam limitando o que você consegue ver durante uma investigação: traces com amostragem, logs sem índice, métricas agregadas e janelas curtas de retenção reduzem o contexto disponível justamente quando ele é mais necessário. O ClickStack é baseado no ClickHouse, que, para grandes cargas de trabalho de logs e tracing, pode ser mais de 100x mais econômico do que o Datadog. É essa diferença na economia de armazenamento que faz valer a pena executar o ClickStack junto com o Datadog:
  • Retenção mais longa. Defina a retenção de acordo com suas necessidades operacionais, e não com o seu orçamento, e mantenha os eventos de que você pode precisar semanas ou meses depois.
  • Dados com fidelidade total. Armazene todos os logs e traces sem amostragem, para que as investigações sejam feitas com dados completos, e não com apenas um subconjunto.
  • Sem limites de taxa da API. Consulte sua telemetria como um banco de dados, em vez de usar uma API tarifada, sem throttling por consulta ou por endpoint.
  • Acesso completo a SQL. Analise logs, métricas e traces com SQL e faça join deles com dados de negócio ou de infraestrutura já presentes no ClickHouse.
  • Cargas de trabalho agênticas. Exponha sua telemetria a agentes de IA por meio do servidor MCP do ClickStack e execute consultas analíticas ilimitadas diretamente no ClickHouse.
A telemetria com fidelidade total é especialmente valiosa para investigações agênticas. Um agente não consegue raciocinar sobre um evento que foi descartado antes de a investigação começar, e precisa de histórico suficiente para comparar um incidente atual com falhas anteriores, mudanças de comportamento e padrões de mais longa duração.

​
Como o receiver do Datadog funciona

Em uma implantação típica do OpenTelemetry, a telemetria é enviada para um coletor OpenTelemetry antes de chegar a um backend. O coletor recebe dados de coletores em modo agent e de SDKs do OpenTelemetry que instrumentam aplicações, aplica filtros ou transformações, agrupa eventos em lotes e os exporta para o destino de destino. O receiver do Datadog adiciona outra entrada a essa arquitetura. Ele expõe um endpoint que entende os protocolos usados por agentes e SDKs do Datadog e converte os payloads recebidos do Datadog para o modelo de dados do OpenTelemetry. A partir daí, eles passam pelo pipeline normal do coletor como qualquer outra telemetria. Os agentes do Datadog existentes são simplesmente reconfigurados para enviar logs e traces para o receiver em execução em um ClickStack collector. As aplicações mantêm seus SDKs do Datadog existentes, e os agentes já implantados em toda a sua infraestrutura permanecem no lugar. Como um pipeline de coletor pode usar mais de um exporter, a mesma telemetria pode ser enviada para o Datadog e para o ClickStack ao mesmo tempo. É isso que torna possível a avaliação lado a lado e a operação paralela de longo prazo: você compara as duas plataformas usando dados idênticos e depois decide de forma independente se quer migrar.

​
O que o receiver processa

O receiver traduz payloads do Datadog para a representação correta no OpenTelemetry, para que o ClickStack possa interpretar, correlacionar e consultar os dados sem lógica específica do Datadog:
  • Registros de log. Os timestamps em milissegundos do Datadog são convertidos em nanossegundos e usados para preencher os campos de timestamp, timestamp observado, body e severidade do OpenTelemetry, para que os registros não apareçam mais no Unix epoch.
  • Atributos de recurso e severidade. Status do Datadog, como info, warn e error, são mapeados para os correspondentes SeverityNumber e SeverityText do OpenTelemetry. Hostnames, nomes de serviço, ambientes e tags conhecidas de contêiner, Cloud e Kubernetes são promovidos a atributos de recurso padrão.
  • Correlação entre trace e log. Os campos dd.trace_id e dd.span_id preenchem os identificadores de trace e span do OpenTelemetry, e o receiver reconstrói trace IDs completos de 128 bits a partir da representação dividida do Datadog. Habilitado por padrão, isso permite correlacionar logs e spans originados do Datadog com serviços instrumentados usando OpenTelemetry.
  • Logs JSON estruturados. Uma opção decode_json_message, habilitada por padrão, faz o processamento de JSON que normalmente acontece no backend do Datadog, extraindo o body, timestamp, severidade, identificadores de trace, campos de recurso e os atributos restantes.
  • Compatibilidade com agentes atuais. O Datadog Agent 7.59 e versões posteriores compacta payloads HTTP com Zstandard por padrão. O receiver oferece suporte a Zstandard junto com gzip, para que os agentes atuais se conectem sem que seus payloads sejam rejeitados.
Essas mudanças estão incluídas na distribuição do ClickStack collector e são configuradas automaticamente, mas também estão disponíveis no projeto OpenTelemetry Collector Contrib.

​
Habilitando o receiver do Datadog

O receiver do Datadog está incluído na distribuição ClickStack do coletor OpenTelemetry e fica escutando na porta 8126. Ele vem desabilitado por padrão e pode ser habilitado com a variável de ambiente ENABLE_DATADOG_RECEIVER. Depois de habilitado, aponte seu agente do Datadog para o receiver e autentique-o com uma chave de ingestão do ClickStack. A origem dessa chave depende da sua implantação: com Managed ClickStack, você executa um coletor standalone e define a chave manualmente na inicialização; com Open Source ClickStack, a chave é gerada para você e copiada da interface do ClickStack (HyperDX). Selecione sua implantação abaixo.
Com o Managed ClickStack, você implanta um coletor ClickStack independente que faz ingestão no seu serviço do ClickHouse Cloud. Você protege o coletor na inicialização com um token de autenticação escolhido por você e reutiliza esse mesmo token como a chave de API do agente do Datadog.
1

Implantar um coletor com o receiver habilitado

ClickStack OpenTelemetry collector vs coletor OpenTelemetry padrãoO receiver do Datadog já vem integrado e pré-configurado na distribuição ClickStack do coletor OpenTelemetry. Se você preferir usar a distribuição padrão OpenTelemetry Collector Contrib, precisará configurar o receiver por conta própria. Todas as nossas alterações e melhorias no receiver são enviadas para o upstream, então elas também estão disponíveis lá. Para opções de configuração, consulte o README do receiver do Datadog.
Execute o coletor ClickStack independente, apontando-o para o seu serviço do ClickHouse Cloud. Habilite o receiver do Datadog com ENABLE_DATADOG_RECEIVER=true, exponha a porta 8126 e proteja a ingestão definindo seu próprio OTLP_AUTH_TOKEN:
O receiver agora está disponível em http://localhost:8126, e o token em OTLP_AUTH_TOKEN é a chave que você deve passar ao agente do Datadog. Para mais detalhes sobre como proteger o coletor, incluindo o equivalente em Helm, consulte “Protegendo o coletor”.
2

Configurar o agente do Datadog

Atualize o arquivo de configuração do agente em /opt/datadog-agent/etc/datadog.yaml para enviar logs, traces e métricas ao receiver. Use o valor de OTLP_AUTH_TOKEN como a chave de API e aponte cada destino para o endpoint do receiver:
Esta configuração:
  • Envia métricas, traces e logs ao receiver em vez de enviá-los ao Datadog.
  • Desabilita o endpoint de ingestão de métricas v3, já que o ClickStack oferece suporte ao endpoint de métricas Datadog v2.
  • Desativa remote updates e remote configuration, que dependem do backend do Datadog.
3

Reiniciar o agente

Reinicie o agente do Datadog para que ele carregue a nova configuração. No macOS:
A telemetria do agente agora flui para o ClickStack, onde você pode explorá-la no HyperDX.

​
Exemplo prático

O exemplo a seguir usa um aplicativo de exemplo para mostrar o fluxo completo de um app instrumentado, passando pelo agente do Datadog até chegar ao ClickStack.
1

Clone e execute o aplicativo de exemplo

O exemplo usa o app de demonstração do Hacker News, instrumentado com Datadog na branch datadog-instrumentation. Clone essa branch:
Siga as instruções no README para executar o app.
2

Inicie o ClickStack com o receiver habilitado

Inicie a imagem all-in-one com o receiver do Datadog habilitado. Aqui, mapeamos o receiver para a porta do host 18126 para evitar conflito com o agente local do Datadog, que também usa 8126:
O receiver está disponível em http://127.0.0.1:18126.
3

Instale e configure o agente do Datadog

Instale o agente do Datadog. No macOS:
Atualize /opt/datadog-agent/etc/datadog.yaml para apontar para o receiver na porta 18126, usando sua chave de ingestão do ClickStack como chave de API, e depois reinicie o agente:
Consulte Habilitando o receiver do Datadog para ver a configuração completa do agente e saber onde encontrar sua chave de ingestão.
4

Explore sua telemetria no ClickStack

Abra a interface do HyperDX em http://localhost:8080 e explore os traces, logs e métricas capturados pelo agente do Datadog.

​
O que você pode migrar hoje

O receiver do Datadog é um componente alpha no OpenTelemetry Collector Contrib e está marcado como experimental na distribuição do ClickStack collector, por isso exige uma feature flag para ser habilitado. O receiver foi amplamente testado com workloads de logs e traces e é recomendado para avaliar o ClickStack com esses sinais. Métricas funcionam, mas ainda exigem mais testes e desenvolvimento. No momento, o receiver oferece suporte aos endpoints de ingestão de métricas v1 e v2 do Datadog, e os agentes que usam versões mais recentes do protocolo precisam ser configurados explicitamente para enviar métricas por um endpoint compatível. Por enquanto, o receiver oferece uma forma rápida de avaliar o ClickStack quando suas aplicações já usam SDKs do Datadog ou sua infraestrutura executa agentes do Datadog. Execute ambos os pipelines em paralelo, valide como seus dados são representados e consultados no ClickStack e, em seguida, decida se vale a pena prosseguir com uma migração mais ampla. Se a avaliação mostrar benefícios claros, a mesma arquitetura dará suporte a uma migração gradual, mantendo a instrumentação atual do Datadog enquanto os serviços migram para OpenTelemetry ao longo do tempo.
Última modificação em 23 de julho de 2026