ResumoEste guia mostra como enviar telemetria para o ClickStack a partir de OpenTelemetry Collectors gerenciados pelo Telflo. Você aprenderá a:
- Criar uma configuração de collector no editor visual do Telflo ou pela CLI
- Enviar a telemetria para o ClickStack open source ou Managed, ou gravá-la diretamente no ClickHouse
- Implantar configurações remotamente em uma frota de collectors
- Confirmar que a telemetria chega ao ClickStack ou às suas tabelas do ClickHouse
O que é o Telflo?
O Telflo é um control plane neutro em relação a fornecedores para OpenTelemetry Collectors, que oferece gerenciamento centralizado da configuração dos collectors de toda uma frota. Ele torna grandes frotas administráveis por meio de um editor visual, testes de pipeline e implantação remota de configurações. O Telflo gerencia builds padrão do collector OpenTelemetry upstream, sem distribuição específica do Telflo e sem agent proprietário, de modo que os collectors que suas equipes já executam continuam no mesmo build. O Telflo também pode ser acessado fora do navegador, por meio de uma interface de linha de comando. Combine isso com o MCP server do ClickStack e o mesmo agent que consulta sua telemetria poderá corrigir o pipeline que a produziu.Por que Telflo + ClickStack?
O ClickStack cuida da ingestão, do armazenamento e das consultas analíticas em grande volume. O Telflo opera de forma centralizada a frota de OpenTelemetry Collectors que o alimenta, abrangendo hosts, clusters e regiões. O Telflo oferece:- Gerenciamento centralizado de OpenTelemetry Collectors em hosts, contêineres e Kubernetes
- Edição visual de pipelines, com rollouts controlados para toda a frota ou para um único grupo
- Alterações verificadas com telemetria de amostra antes de chegarem aos collectors em produção
- Roteamento da mesma telemetria para o ClickStack e outros destinos simultaneamente
- Visibilidade da frota: quais collectors estão online, o que cada um está executando e quais sofreram desvios
Pré-requisitos
- Um destino: Open Source ClickStack, Managed ClickStack ou uma instância autogerenciada do ClickHouse
- Conta Telflo (crie uma conta em telflo.com)
- Um ambiente onde executar os collectors: uma VM ou um cluster do Kubernetes
- Open Source ClickStack: o endpoint OTLP do seu ClickStack (
4318para HTTP,4317para gRPC) e sua API key de ingestão, disponível no HyperDX em Team Settings → API Keys (veja a documentação aqui para referência) - Managed ClickStack: o endpoint do seu serviço ClickHouse Cloud (porta
8443) e um usuário de ingestão (consulte Criando um usuário de ingestão) - ClickHouse autogerenciado: o endpoint do seu ClickHouse, um banco de dados para as tabelas do ClickStack e um usuário com permissão para criá-las e escrever nelas (consulte Criando um usuário de ingestão)
- Conectividade de rede dos collectors até o endpoint do seu ClickStack ou ClickHouse
Integre o ClickStack com o Telflo
1
Crie uma configuração do collector
- Faça login no Telflo. Na lista Configurations, clique em New Configuration e, em seguida, em Blank configuration.
- Em Name Your Configuration, informe um nome e clique em Create.
- Adicione receivers: arraste um da paleta para o canvas para cada tipo de telemetria que você coleta.
- Adicione processors: Memory Limiter e Batch, além de quaisquer outros necessários para estruturar os dados antes que eles saiam do collector. Consulte a lista completa de processors compatíveis com o Telflo.
2
Adicione o exporter
Os três caminhos usam o mesmo editor, o mesmo passo de publicação e a mesma frota; apenas o exporter muda. Escolha a aba correspondente à sua implantação: o Open Source ClickStack recebe OTLP com uma chave de ingestão; o Managed ClickStack e o ClickHouse autogerenciado recebem gravações diretas nas tabelas do ClickStack.Trace conexões dos receivers, passando pelos processors, até o exporter, um pipeline por sinal. A linha de status informa config valid ou o número de erros a corrigir, e a aba YAML exibe a configuração gerada.Antes de colocar qualquer coisa em produção, você pode enviar telemetria de amostra pela configuração e verificar o resultado obtido na outra ponta. Consulte testes no Telflo. Como alternativa, você pode descrever o que pretende fazer e o assistente de IA do Telflo, aberto pelo botão AI na barra de ferramentas, monta, valida e testa a configuração para você. Seu próprio agente pode fazer o mesmo por meio da CLI do Telflo.
- Open Source ClickStack
- Managed ClickStack
- Self-managed ClickHouse
- Arraste o exporter OTLP/HTTP para o canvas.
- Defina Endpoint com o endpoint OTLP HTTP do seu ClickStack, por exemplo
http://clickstack.example.com:4318. - Em HTTP Headers, clique em Add header e informe
authorizationcomo Header name e${env:CLICKSTACK_INGESTION_KEY}como Header value. O Telflo solicita esse valor no momento da instalação dos collectors, de modo que a chave nunca fica armazenada na configuração.
4317 com o mesmo header em gRPC Metadata Headers.3
Publicar uma versão
Clique em Publish na barra de ferramentas. As versões publicadas são somente leitura; para continuar iterando, clique em Create New Version.
4
Crie uma frota e implemente-a
- Acesse Fleet, clique em New Fleet e escolha onde os collectors serão executados: em VMs ou no Kubernetes. Informe um Name e clique em Create fleet.
- Na aba Deploy Groups da fleet, clique em Assign no grupo Default e escolha a configuration publicada e a version.
- Clique em Install no grupo e informe um valor para cada environment variable referenciada pela sua configuration; o Telflo os adiciona ao comando de instalação. Execute esse comando no local onde os collectors devem ser executados, seguindo as instruções de instalação do Telflo. Ele carrega o token de instalação da fleet junto com o seu valor, portanto trate-o como informação sensível.
- Na aba Collectors, os collectors reportam Pending pickup, depois Applying e, por fim, In sync.
5
Verifique a telemetria
Abra o HyperDX e busque um dos seus serviços na visualização Busca; use o Chart Explorer para métricas. Com o Managed ClickStack, abra seu serviço no console do ClickHouse Cloud e clique em Launch ClickStack. Com o ClickHouse autogerenciado, consulte diretamente as tabelas do ClickStack, por exemplo
SELECT ServiceName, count() FROM otel_logs GROUP BY ServiceName.Configuração avançada
Fan-out routing
A mesma telemetria pode ser enviada simultaneamente ao ClickStack para armazenamento de longo prazo, a outra plataforma durante uma migração e a um SIEM para análise de segurança. Adicione os exporters ao canvas e conecte-os aos pipelines que devem alimentá-los, ou comece a partir de um pipeline pronto na biblioteca de fluxos da Telflo.Compressão e desempenho
- Exporters OTLP/HTTP e OTLP: mantenha Compression em gzip.
- ClickHouse exporter: mantenha Async Insert ativado, deixe Compression em lz4 e adicione um processor Batch antes dele no pipeline. Consulte Otimizando inserts.
Próximos passos
- Crie dashboards: crie visualizações no HyperDX para logs, metrics e traces
- Configure alerts: configure alerts no ClickStack para conditions críticas
- Refine com o AI assistant: peça a ele para ajustar um pipeline ou sugerir testes
- Se você está migrando de outro fornecedor: os flows dão conta da transição, substituindo os agents já instalados na sua infraestrutura e enviando os dados simultaneamente para os dois backends enquanto você os compara