> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Enviando OpenTelemetry para o ClickStack com o Telflo

> Crie e implante configurações do OpenTelemetry Collector que enviam telemetria para o ClickStack ou a gravam diretamente no ClickHouse, com o Telflo gerenciando a frota de collectors

Integração com parceiro

> [!NOTE]
>
> **Resumo**
>
> Este 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
>
> Tempo necessário: 15-20 minutos

## 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](https://docs.telflo.com/docs/cli/). Combine isso com o [MCP server do ClickStack](https://clickhouse.com/docs/pt-BR/clickstack/mcp.md) 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

> [!TIP]
>
> **Principais pontos**
>
> * **O ClickStack faz ingestão, armazena e consulta dados em escala**
> * **O Telflo opera a frota de collectors que o alimenta**

## Pré-requisitos

* Um destino: [Open Source ClickStack](https://clickhouse.com/docs/pt-BR/clickstack/getting-started/oss.md), [Managed ClickStack](https://clickhouse.com/docs/pt-BR/clickstack/getting-started/managed.md) ou uma instância autogerenciada do ClickHouse
* Conta Telflo ([crie uma conta em telflo.com](https://telflo.com))
* Um ambiente onde executar os collectors: uma VM ou um cluster do Kubernetes
* **Open Source ClickStack**: o endpoint OTLP do seu ClickStack (`4318` para HTTP, `4317` para 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](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/opentelemetry.md#sending-otel-data))
* **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](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/collector.md#creating-an-ingestion-user))
* **ClickHouse autogerenciado**: o endpoint do seu ClickHouse, um banco de dados para as [tabelas do ClickStack](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/schemas.md) e um usuário com permissão para criá-las e escrever nelas (consulte [Criando um usuário de ingestão](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/collector.md#creating-an-ingestion-user-oss))
* 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**

1. Faça login no Telflo. Na lista **Configurations**, clique em **New Configuration** e, em seguida, em **Blank configuration**.
2. Em **Name Your Configuration**, informe um nome e clique em **Create**.
3. Adicione receivers: arraste um da paleta para o canvas para cada tipo de telemetria que você coleta.
4. 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](https://docs.telflo.com/docs/build/components#processors).

**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.

**Open Source ClickStack**

1. Arraste o exporter **OTLP/HTTP** para o canvas.
2. Defina **Endpoint** com o endpoint OTLP HTTP do seu ClickStack, por exemplo `http://clickstack.example.com:4318`.
3. Em **HTTP Headers**, clique em **Add header** e informe `authorization` como **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.

Para gRPC, use o exporter **OTLP** na porta `4317` com o mesmo header em **gRPC Metadata Headers**.

**Managed ClickStack**

O Managed ClickStack não inclui um collector gateway, portanto não há um endpoint OTLP hospedado para onde enviar a telemetria. O collector que você configura aqui passa a ser esse [gateway](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/collector.md#collector-roles): adicione a ele um receiver **OTLP** junto com o ClickHouse exporter, e ele passará a gravar no seu ClickHouse Cloud service. Seus SDKs e collectors agent então enviam OTLP para ele nas portas `4318` (HTTP) ou `4317` (gRPC).

1. Arraste o exporter **ClickHouse** para o canvas.
2. Preencha **Endpoint** com o endpoint do seu ClickHouse Cloud service (porta `8443`), defina **Database** como `default` e informe em **Username** o seu usuário de ingestão.
3. Defina **Password** como `${env:CLICKHOUSE_PASSWORD}`. O Telflo solicita esse valor no momento da instalação dos collectors, de modo que a credencial nunca fica armazenada na configuração.
4. Em **Schema & Tables**: se as [tabelas do ClickStack](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/schemas.md) ainda não existirem, mantenha **Create Schema on Startup** ativado para que o exporter as crie. Desative essa opção assim que elas existirem.

Mantenha o **Batch** antes do exporter: o ClickHouse tem melhor desempenho com inserts em lote. Se você já executa um [collector do ClickStack](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/collector.md#configuring-the-collector) como seu gateway OTLP, pode, em vez disso, seguir os passos de Open Source ClickStack, usando como valor do header o [`OTLP_AUTH_TOKEN`](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/collector#securing-the-collector) definido nesse collector.

**Self-managed ClickHouse**

O collector que você configura aqui atua como seu [gateway](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/collector.md#collector-roles): adicione a ele um receiver **OTLP** junto com o ClickHouse exporter. Seus SDKs e collectors agent enviam OTLP para ele, e ele grava no ClickHouse.

1. Arraste o exporter **ClickHouse** para o canvas.
2. Preencha **Endpoint** (por exemplo, `https://clickhouse.example.com:8443`), **Database** e **Username**, apontando **Database** para o banco de dados em que residem as tabelas do ClickStack.
3. Defina **Password** como `${env:CLICKHOUSE_PASSWORD}`. O Telflo solicita esse valor no momento da instalação dos collectors, de modo que a credencial nunca fica armazenada na configuração.
4. Em **Schema & Tables**: se as tabelas do ClickStack ainda não existirem, mantenha **Create Schema on Startup** ativado para que o exporter as crie. Desative essa opção assim que elas existirem.

Mantenha o **Batch** antes do exporter: o ClickHouse tem melhor desempenho com inserts em lote. Se você já executa um [collector do ClickStack](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/collector.md#configuring-the-collector) como seu gateway OTLP, pode, em vez disso, seguir os passos de Open Source ClickStack, usando como valor do header o [`OTLP_AUTH_TOKEN`](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/collector#securing-the-collector) definido nesse collector.

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.

![Um pipeline do coletor no editor Telflo com o exportador do ClickHouse configurado](https://mintcdn.com/private-7c7dfe99/5NhXl45F-rkC2yU0/images/clickstack/telflo/telflo-configuration.webp?fit=max\&auto=format\&n=5NhXl45F-rkC2yU0\&q=85\&s=4b8c285f2ceaef0b8d68dfeb998fe899)

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](https://docs.telflo.com/docs/testing/overview). 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](https://docs.telflo.com/docs/cli/).

**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**

1. 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**.
2. Na aba **Deploy Groups** da fleet, clique em **Assign** no grupo **Default** e escolha a configuration publicada e a version.
3. 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](https://docs.telflo.com/docs/fleet-management/install-collectors). Ele carrega o token de instalação da fleet junto com o seu valor, portanto trate-o como informação sensível.
4. Na aba **Collectors**, os collectors reportam **Pending pickup**, depois **Applying** e, por fim, **In sync**.

Para aplicar uma alteração, publique uma nova version e atribua-a ao grupo; para reverter, atribua uma version implantada anteriormente.

![Uma fleet do Telflo com todos os collectors sincronizados após um rollout](https://mintcdn.com/private-7c7dfe99/5NhXl45F-rkC2yU0/images/clickstack/telflo/telflo-fleet.webp?fit=max\&auto=format\&n=5NhXl45F-rkC2yU0\&q=85\&s=fc39b525dff977bd4f637f2b5efb3f78)

**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](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/schemas.md), 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](https://telflo.com/flows).

### 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](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/collector.md#optimizing-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](https://telflo.com/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

## Leia mais

* [Documentação do Telflo](https://docs.telflo.com/docs)
* [Quickstart: de um canvas vazio a um collector implantado](https://docs.telflo.com/docs/getting-started/quickstart)
* [Testando configurações do collector](https://docs.telflo.com/docs/testing/overview)
* [Gerenciamento de frota no Telflo](https://docs.telflo.com/docs/fleet-management/overview)
* [Instalando collectors](https://docs.telflo.com/docs/fleet-management/install-collectors)
* [Ingestão com OpenTelemetry](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/opentelemetry.md)
* [Schemas de tabela do ClickStack](https://clickhouse.com/docs/pt-BR/clickstack/ingesting-data/schemas.md)