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

# Отправка данных OpenTelemetry в ClickStack с помощью Telflo

> Создавайте и разворачивайте конфигурации OpenTelemetry Collector, которые отправляют телеметрию в ClickStack или записывают её напрямую в ClickHouse, а Telflo управляет парком коллекторов

Партнерская интеграция

> [!NOTE]
>
> **Кратко**
>
> В этом руководстве показано, как отправлять телеметрию в ClickStack из коллекторов OpenTelemetry, управляемых Telflo. Вы узнаете, как:
>
> * Создать конфигурацию коллектора в визуальном редакторе Telflo или через CLI
> * Отправлять телеметрию в ClickStack с открытым исходным кодом или в Управляемый ClickStack, либо записывать её напрямую в ClickHouse
> * Удалённо развёртывать конфигурации на парк коллекторов
> * Убедиться, что телеметрия попадает в ClickStack или в ваши таблицы ClickHouse
>
> Требуемое время: 15–20 минут

## Что такое Telflo?

Telflo — это независимый от поставщика control plane для OpenTelemetry Collector, обеспечивающий централизованное управление конфигурацией коллекторов в масштабах всего парка. Визуальный редактор, тесты конвейеров и удалённое развёртывание конфигураций делают крупные парки управляемыми. Telflo работает со стандартными upstream-сборками OpenTelemetry Collector: нет ни отдельной сборки Telflo, ни проприетарного агента, поэтому коллекторы, которые уже запущены у ваших команд, остаются на той же сборке.

Telflo доступен не только в браузере, но и через [интерфейс командной строки](https://docs.telflo.com/docs/cli/). Объедините его с [MCP-сервером ClickStack](https://clickhouse.com/docs/ru/clickstack/mcp.md) — и тот же агент, который выполняет запросы к вашей телеметрии, сможет исправить конвейер, который её сформировал.

## Почему Telflo + ClickStack?

ClickStack обеспечивает ингестию, хранение и аналитические запросы на больших объёмах данных. Telflo централизованно управляет парком OpenTelemetry Collector, которые его наполняют, — на хостах, в кластерах и регионах.

Telflo предоставляет:

* Централизованное управление OpenTelemetry Collector на хостах, в контейнерах и в Kubernetes
* Визуальное редактирование конвейеров с контролируемым развёртыванием на весь парк или на отдельную группу
* Проверку изменений на образцах телеметрии до того, как они попадут на продакшн-коллекторы
* Маршрутизацию одной и той же телеметрии одновременно в ClickStack и другие пункты назначения
* Обзор парка: какие коллекторы онлайн, что запущено на каждом из них и где конфигурация разошлась с эталонной

> [!TIP]
>
> **Ключевые выводы**
>
> * **ClickStack принимает, хранит и обрабатывает запросы в большом масштабе**
> * **Telflo управляет парком коллекторов, которые его наполняют**

## Предварительные требования

* Пункт назначения: [ClickStack с открытым исходным кодом](https://clickhouse.com/docs/ru/clickstack/getting-started/oss.md), [Управляемый ClickStack](https://clickhouse.com/docs/ru/clickstack/getting-started/managed.md) или самоуправляемый экземпляр ClickHouse
* Аккаунт Telflo ([создайте аккаунт на telflo.com](https://telflo.com))
* Среда для запуска коллекторов: ВМ или кластер Kubernetes
* **ClickStack с открытым исходным кодом**: конечная точка OTLP вашего ClickStack (`4318` для HTTP, `4317` для gRPC) и ключ API для приёма данных, который можно найти в HyperDX в разделе **Team Settings → API Keys** ([документация для справки](https://clickhouse.com/docs/ru/clickstack/ingesting-data/opentelemetry.md#sending-otel-data))
* **Управляемый ClickStack**: конечная точка вашего сервиса ClickHouse Cloud (порт `8443`) и пользователь для ингестии (см. [Создание пользователя для ингестии](https://clickhouse.com/docs/ru/clickstack/ingesting-data/collector.md#creating-an-ingestion-user))
* **Self-managed ClickHouse**: конечная точка вашего ClickHouse, база данных для [таблиц ClickStack](https://clickhouse.com/docs/ru/clickstack/ingesting-data/schemas.md) и пользователь с правами на их создание и запись в них (см. [Создание пользователя для ингестии](https://clickhouse.com/docs/ru/clickstack/ingesting-data/collector.md#creating-an-ingestion-user-oss))
* Сетевая доступность вашей конечной точки ClickStack или ClickHouse с хостов коллекторов

## Интеграция ClickStack с Telflo

**1. Создайте конфигурацию коллектора**

1. Войдите в Telflo. В списке **Configurations** нажмите **New Configuration**, затем **Blank configuration**.
2. В поле **Name Your Configuration** введите имя и нажмите **Create**.
3. Добавьте приёмники: для каждого типа собираемой телеметрии перетащите на холст соответствующий элемент из палитры.
4. Добавьте процессоры: **Memory Limiter** и **Batch**, а также любые другие, необходимые для приведения данных к нужному виду перед отправкой из коллектора. См. [полный список процессоров, поддерживаемых Telflo](https://docs.telflo.com/docs/build/components#processors).

**2. Добавьте экспортёр**

Все три варианта используют один и тот же редактор, один и тот же шаг публикации и один и тот же парк агентов; различается только exporter. Выберите вкладку, соответствующую вашему развертыванию: ClickStack с открытым исходным кодом принимает OTLP с ключом ингестии; Управляемый ClickStack и самоуправляемый ClickHouse принимают прямую запись в таблицы ClickStack.

> [tab] Open Source ClickStack
>
> 1. Перетащите экспортёр **OTLP/HTTP** на холст.
> 2. Укажите в поле **Endpoint** конечную точку OTLP HTTP вашего ClickStack, например `http://clickstack.example.com:4318`.
> 3. В разделе **HTTP Headers** нажмите **Add header**, затем введите `authorization` в поле **Header name** и `${env:CLICKSTACK_INGESTION_KEY}` в поле **Header value**. Telflo запрашивает это значение при установке коллекторов, поэтому ключ никогда не сохраняется в конфигурации.
>
> Для gRPC используйте экспортёр **OTLP** на порту `4317` с тем же заголовком в разделе **gRPC Metadata Headers**.

> [tab] Managed ClickStack
>
> Управляемый ClickStack не поставляется с коллектором-шлюзом, поэтому размещённой конечной точки OTLP для отправки телеметрии нет. Именно настраиваемый здесь коллектор и становится таким [шлюзом](https://clickhouse.com/docs/ru/clickstack/ingesting-data/collector.md#collector-roles): добавьте ему приёмник **OTLP** вместе с экспортёром ClickHouse, и он будет записывать данные в ваш сервис ClickHouse Cloud. Ваши SDK и коллекторы-агенты после этого отправляют в него OTLP на порт `4318` (HTTP) или `4317` (gRPC).
>
> 1. Перетащите экспортёр **ClickHouse** на холст.
> 2. Заполните поле **Endpoint** конечной точкой вашего сервиса ClickHouse Cloud (порт `8443`), укажите в **Database** значение `default`, а в **Username** — пользователя для ингестии.
> 3. Укажите в поле **Password** значение `${env:CLICKHOUSE_PASSWORD}`. Telflo запрашивает это значение при установке коллекторов, поэтому учётные данные никогда не сохраняются в конфигурации.
> 4. В разделе **Schema & Tables**: если [таблицы ClickStack](https://clickhouse.com/docs/ru/clickstack/ingesting-data/schemas.md) ещё не созданы, оставьте параметр **Create Schema on Startup** включённым — экспортёр создаст их. Отключите его, как только таблицы появятся.
>
> Оставьте **Batch** перед экспортёром: ClickHouse работает эффективнее всего при вставках батчами. Если у вас уже есть [коллектор ClickStack](https://clickhouse.com/docs/ru/clickstack/ingesting-data/collector.md#configuring-the-collector) в роли шлюза OTLP, вы можете вместо этого выполнить шаги для Open Source ClickStack, указав в качестве значения заголовка [`OTLP_AUTH_TOKEN`](https://clickhouse.com/docs/ru/clickstack/ingesting-data/collector#securing-the-collector), заданный на этом коллекторе.

> [tab] Self-managed ClickHouse
>
> Настраиваемый здесь коллектор выступает вашим [шлюзом](https://clickhouse.com/docs/ru/clickstack/ingesting-data/collector.md#collector-roles): добавьте ему приёмник **OTLP** вместе с экспортёром ClickHouse. Ваши SDK и коллекторы-агенты отправляют в него OTLP, а он записывает данные в ClickHouse.
>
> 1. Перетащите экспортёр **ClickHouse** на холст.
> 2. Заполните поля **Endpoint** (например, `https://clickhouse.example.com:8443`), **Database** и **Username**, указав в **Database** ту базу данных, в которой находятся таблицы ClickStack.
> 3. Укажите в поле **Password** значение `${env:CLICKHOUSE_PASSWORD}`. Telflo запрашивает это значение при установке коллекторов, поэтому учётные данные никогда не сохраняются в конфигурации.
> 4. В разделе **Schema & Tables**: если таблицы ClickStack ещё не созданы, оставьте параметр **Create Schema on Startup** включённым — экспортёр создаст их. Отключите его, как только таблицы появятся.
>
> Оставьте **Batch** перед экспортёром: ClickHouse работает эффективнее всего при вставках батчами. Если у вас уже есть [коллектор ClickStack](https://clickhouse.com/docs/ru/clickstack/ingesting-data/collector.md#configuring-the-collector) в роли шлюза OTLP, вы можете вместо этого выполнить шаги для Open Source ClickStack, указав в качестве значения заголовка [`OTLP_AUTH_TOKEN`](https://clickhouse.com/docs/ru/clickstack/ingesting-data/collector#securing-the-collector), заданный на этом коллекторе.

Проведите связи от приёмников через процессоры к экспортёру — по одному конвейеру на каждый тип сигнала. В строке состояния отображается **config valid** либо количество ошибок, которые нужно исправить, а на вкладке **YAML** — сгенерированная конфигурация.

![Конвейер коллектора в редакторе Telflo с настроенным экспортёром ClickHouse](https://mintcdn.com/private-7c7dfe99/5NhXl45F-rkC2yU0/images/clickstack/telflo/telflo-configuration.webp?fit=max\&auto=format\&n=5NhXl45F-rkC2yU0\&q=85\&s=4b8c285f2ceaef0b8d68dfeb998fe899)

Перед развёртыванием вы можете пропустить через конфигурацию тестовую телеметрию и посмотреть, что получится на выходе. См. [тестирование в Telflo](https://docs.telflo.com/docs/testing/overview). Кроме того, вы можете описать, чего хотите добиться, и ИИ-ассистент Telflo, который открывается кнопкой **AI** на панели инструментов, сам построит, проверит и протестирует конфигурацию. Ваш собственный агент может сделать то же самое через [Telflo CLI](https://docs.telflo.com/docs/cli/).

**3. Опубликовать версию**

Нажмите **Publish** на панели инструментов. Опубликованные версии доступны только для чтения; чтобы продолжить доработку, нажмите **Create New Version**.

**4. Создайте группу агентов и разверните её**

1. Перейдите в раздел **Fleet**, нажмите **New Fleet** и выберите, где будут работать ваши collectors — на ВМ или в Kubernetes. Укажите **Name** и нажмите **Create fleet**.
2. На вкладке **Deploy Groups** этого парка нажмите **Assign** для группы **Default** и выберите опубликованную configuration и её version.
3. Нажмите **Install** для группы и укажите значение для каждой переменной окружения, на которую ссылается ваша configuration; Telflo добавит их в команду установки. Выполните эту команду там, где должны работать collectors, [следуя инструкциям по установке Telflo](https://docs.telflo.com/docs/fleet-management/install-collectors). Команда содержит install token парка вместе с вашим значением, поэтому обращайтесь с ней как с конфиденциальными данными.
4. На вкладке **Collectors** collectors сообщают о состоянии **Pending pickup**, затем **Applying** и, наконец, **In sync**.

Чтобы выполнить rollout изменения, опубликуйте новую version и назначьте её группе; чтобы откатиться, назначьте ранее развёрнутую version.

![Парк Telflo, в котором после rollout все collectors синхронизированы](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. Проверьте телеметрию**

Откройте HyperDX и найдите один из своих сервисов в представлении **Search**; для метрик используйте **Chart Explorer**. В случае Managed ClickStack откройте свой сервис в консоли ClickHouse Cloud и нажмите **Launch ClickStack**. В случае самоуправляемого ClickHouse обращайтесь к [таблицам ClickStack](https://clickhouse.com/docs/ru/clickstack/ingesting-data/schemas.md) напрямую, например: `SELECT ServiceName, count() FROM otel_logs GROUP BY ServiceName`.

## Расширенная конфигурация

### Fan-out маршрутизация

Одни и те же данные телеметрии могут одновременно отправляться в ClickStack для долговременного хранения, на другую платформу во время миграции и в SIEM для анализа безопасности. Добавьте экспортёры на холст и подключите их к конвейерам, которые должны передавать в них данные, либо начните с готового конвейера из [библиотеки потоков Telflo](https://telflo.com/flows).

### Сжатие и производительность

* **Экспортеры OTLP/HTTP и OTLP**: оставьте для **Compression** значение gzip.
* **ClickHouse exporter**: оставьте **Async Insert** включённым, для **Compression** — значение lz4, и добавьте перед ним в конвейере процессор **Batch**. См. [Оптимизация вставок](https://clickhouse.com/docs/ru/clickstack/ingesting-data/collector.md#optimizing-inserts).

## Дальнейшие шаги

* **Создайте панели мониторинга**: создавайте визуализации в HyperDX для журналов, метрик и трейсов
* **Настройте алерты**: настройте в ClickStack алерты для критических условий
* **Доработайте с помощью AI assistant**: попросите его скорректировать конвейер или предложить тесты
* **Переходите от другого поставщика**: [flows](https://telflo.com/flows) берут на себя cutover — заменяют агентов, уже развёрнутых на вашем парке машин, и параллельно отправляют данные в оба backend-соединения, пока вы их сравниваете

## Дополнительные материалы

* [Документация Telflo](https://docs.telflo.com/docs)
* [Быстрый старт: от пустого холста до развёрнутого коллектора](https://docs.telflo.com/docs/getting-started/quickstart)
* [Тестирование конфигураций коллектора](https://docs.telflo.com/docs/testing/overview)
* [Управление парком коллекторов в Telflo](https://docs.telflo.com/docs/fleet-management/overview)
* [Установка коллекторов](https://docs.telflo.com/docs/fleet-management/install-collectors)
* [Приём данных с помощью OpenTelemetry](https://clickhouse.com/docs/ru/clickstack/ingesting-data/opentelemetry.md)
* [Схемы таблиц ClickStack](https://clickhouse.com/docs/ru/clickstack/ingesting-data/schemas.md)
