Миграция с Datadog на ClickStack

Миграция платформы обсервабилити обычно означает нечто большее, чем просто смену места хранения данных. Агенты Datadog и SDKs уже могут быть развернуты в тысячах приложений, на хостах, виртуальных машинах и в подах Kubernetes. Если, чтобы просто оценить другой backend, нужно заново инструментировать всё это, миграция превращается в большой проект ещё до того, как начнёт приносить какую-либо пользу. Встроенный в дистрибутив ClickStack приёмник Datadog для OpenTelemetry Collector (OTel) снимает эти первоначальные затраты. Ваши существующие агенты Datadog и SDKs продолжают работать без изменений. Вместо того чтобы отправлять телеметрию в Datadog, вы направляете её в приёмник, который преобразует нативные полезные нагрузки Datadog для логов, трассировок и метрик в модель данных OpenTelemetry и передаёт их через стандартный конвейер коллектора в ClickStack. Поскольку приёмник работает внутри обычного конвейера коллектора, его можно использовать, чтобы:

Оценивать ClickStack параллельно с Datadog, не затрагивая прикладной код, и с помощью существующих агентов отправлять одну и ту же телеметрию в обе платформы.
Упростить миграцию — перейти на ClickStack, сохранив текущий уровень сбора данных и постепенно внедряя инструментацию OpenTelemetry.
Использовать оба стека параллельно в долгосрочной перспективе, применяя каждую платформу там, где она подходит лучше всего.

Почему стоит запускать ClickStack вместе с Datadog

Для большинства команд главная причина вынести данные обсервабилити из Datadog — это стоимость. По мере масштабирования приложений и подключения инструментации к новым сервисам объёмы журналов и трассировок растут, и в какой-то момент приходится выбирать: либо больше тратить, либо хранить меньше телеметрии. В результате такие меры по контролю затрат ограничивают то, что вы можете увидеть во время расследования: сэмплированные трассировки, неиндексированные журналы, агрегированные метрики и короткие сроки хранения уменьшают объём доступного контекста именно тогда, когда он нужнее всего. ClickStack построен на ClickHouse, который для крупных нагрузок, связанных с журналами и трассировкой, может быть более чем в 100 раз экономичнее Datadog. Именно эта разница в экономике хранилища делает использование ClickStack вместе с Datadog оправданным:

Более длительное хранение. Настраивайте сроки хранения в соответствии с эксплуатационными потребностями, а не бюджетом, и сохраняйте события, которые могут понадобиться спустя недели или месяцы.
Данные полной точности. Храните каждый журнал и каждую трассировку без сэмплирования, чтобы расследования проводились по полным данным, а не по их подмножеству.
Без ограничений скорости API. Выполняйте запросы к своей телеметрии как к базе данных, а не через тарифицируемый API, без throttling для отдельных запросов и конечных точек.
Полный доступ к SQL. Анализируйте журналы, метрики и трассировки с помощью SQL и объединяйте их через JOIN с бизнес-данными или данными инфраструктуры, уже хранящимися в ClickHouse.
Агентные сценарии. Сделайте свою телеметрию доступной для ИИ-агентов через сервер ClickStack MCP и выполняйте неограниченное количество аналитических запросов напрямую к ClickHouse.

Телеметрия полной точности особенно ценна для агентных расследований. Агент не может рассуждать о событии, которое было отброшено ещё до начала расследования, и ему нужна достаточная история, чтобы сопоставить текущий инцидент с прежними сбоями, изменениями в поведении и более долгосрочными закономерностями.

Как работает приёмник Datadog

В типичном развертывании OpenTelemetry телеметрия сначала отправляется в OpenTelemetry Collector, а уже затем попадает в бэкенд. Коллектор получает данные от коллекторов, работающих в режиме агента, и от OpenTelemetry SDKs, которыми инструментированы приложения, применяет фильтрацию и преобразования, объединяет события в батчи и экспортирует их в целевой пункт назначения. Приёмник Datadog добавляет в эту архитектуру ещё один источник входящих данных. Он предоставляет конечную точку, которая понимает протоколы, используемые агентами и SDK Datadog, и преобразует входящие полезные нагрузки Datadog в модель данных OpenTelemetry. После этого они проходят через стандартный конвейер коллектора, как и любая другая телеметрия. Существующие агенты Datadog достаточно просто перенастроить так, чтобы они отправляли журналы и трассировки в приёмник, работающий на коллекторе ClickStack. Приложения продолжают использовать существующие SDK Datadog, а агенты, уже развернутые в вашей инфраструктуре, остаются на месте. Поскольку конвейер коллектора может использовать несколько exporter, одну и ту же телеметрию можно одновременно отправлять и в Datadog, и в ClickStack. Именно это делает возможными параллельную оценку и длительную параллельную эксплуатацию: вы сравниваете обе платформы на идентичных данных, а затем отдельно принимаете решение о миграции.

Что обрабатывает приёмник

Приёмник преобразует полезные нагрузки Datadog в корректное представление OpenTelemetry, чтобы ClickStack мог интерпретировать данные, коррелировать их и выполнять по ним запросы без какой-либо специфичной для Datadog логики:

Записи журнала. Временные метки Datadog в миллисекундах преобразуются в наносекунды и используются для заполнения полей OpenTelemetry timestamp, observed timestamp, body и severity, поэтому записи больше не отображаются с временной меткой Unix epoch.
Атрибуты ресурса и severity. Статусы Datadog, такие как info, warn и error, сопоставляются с соответствующими значениями OpenTelemetry SeverityNumber и SeverityText. Имена хостов, имена сервисов, окружения, а также известные теги контейнеров, Cloud и Kubernetes преобразуются в стандартные атрибуты ресурса.
Корреляция трассировок и журналов. Поля dd.trace_id и dd.span_id заполняют идентификаторы trace и span в OpenTelemetry, а приёмник восстанавливает полные 128-битные trace ID из разделённого представления Datadog. Эта возможность включена по умолчанию и позволяет коррелировать журналы и spans из Datadog с сервисами, инструментированными с помощью OpenTelemetry.
Структурированные JSON-журналы. Параметр decode_json_message, включенный по умолчанию, выполняет обработку JSON, которая обычно происходит в backend Datadog: извлекает body, временную метку, severity, идентификаторы трассировки, поля ресурса и оставшиеся атрибуты.
Совместимость с текущими agents. Datadog Agent 7.59 и более поздние версии по умолчанию сжимают HTTP-полезные нагрузки с помощью Zstandard. Приёмник поддерживает Zstandard наряду с gzip, поэтому текущие agents подключаются без отклонения их полезных нагрузок.

Эти изменения входят в дистрибутив коллектора ClickStack и настраиваются автоматически, но также доступны в проекте OpenTelemetry Collector Contrib.

Включение приёмника Datadog

Приёмник Datadog входит в состав дистрибутива ClickStack для OpenTelemetry Collector и прослушивает порт 8126. По умолчанию он отключен и включается с помощью переменной окружения ENABLE_DATADOG_RECEIVER. После включения настройте агент Datadog на отправку данных в этот приёмник и аутентифицируйте его с помощью ключа ингестии ClickStack. Откуда берётся этот ключ, зависит от вашего развертывания: в Управляемом ClickStack вы запускаете автономный коллектор и сами задаёте ключ при запуске, а в Open Source ClickStack ключ создаётся автоматически, и его нужно скопировать из интерфейса ClickStack (HyperDX). Ниже выберите своё развертывание.

Управляемый ClickStack
ClickStack с открытым исходным кодом

С Управляемым ClickStack вы разворачиваете автономный коллектор ClickStack, который выполняет ингестию в ваш сервис ClickHouse Cloud. При запуске вы защищаете коллектор с помощью выбранного вами токена аутентификации и затем используете этот же токен как ключ API агента Datadog.

Разверните коллектор с включенным приёмником

Коллектор ClickStack OpenTelemetry и стандартный OpenTelemetry CollectorПриёмник Datadog встроен в дистрибутив коллектора ClickStack OpenTelemetry и уже предварительно настроен. Если вы предпочитаете использовать стандартный дистрибутив OpenTelemetry Collector Contrib, вам потребуется настроить приёмник самостоятельно. Все наши изменения и улучшения для этого приёмника отправляются в upstream, поэтому там они тоже доступны. Параметры конфигурации см. в README приёмника Datadog.

Запустите автономный коллектор ClickStack, указав в качестве пункта назначения ваш сервис ClickHouse Cloud. Включите приёмник Datadog с помощью ENABLE_DATADOG_RECEIVER=true, откройте порт 8126 и защитите ингестию, задав собственный OTLP_AUTH_TOKEN:

export CLICKHOUSE_ENDPOINT=<HTTPS_ENDPOINT>
export CLICKHOUSE_USER=<CLICKHOUSE_USER>
export CLICKHOUSE_PASSWORD=<CLICKHOUSE_PASSWORD>
export OTLP_AUTH_TOKEN="a_very_secure_string"

docker run --name clickstack-collector \
  -e ENABLE_DATADOG_RECEIVER=true \
  -e OTLP_AUTH_TOKEN=${OTLP_AUTH_TOKEN} \
  -e CLICKHOUSE_ENDPOINT=${CLICKHOUSE_ENDPOINT} \
  -e CLICKHOUSE_USER=${CLICKHOUSE_USER} \
  -e CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD} \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8126:8126 \
  clickhouse/clickstack-otel-collector:latest

Теперь приёмник доступен по адресу http://localhost:8126, а токен из OTLP_AUTH_TOKEN — это ключ, который нужно передать агенту Datadog. Подробнее о защите коллектора, включая эквивалент для Helm, см. в разделе “Защита коллектора”.

Настройте агент Datadog

Обновите файл конфигурации агента /opt/datadog-agent/etc/datadog.yaml, чтобы отправлять журналы, трассировки и метрики в приёмник. Используйте значение OTLP_AUTH_TOKEN как ключ API и укажите конечную точку приёмника для каждого пункта назначения:

api_key: "<YOUR_OTLP_AUTH_TOKEN>"

# Пункт назначения метрик
dd_url: "http://localhost:8126"

# ClickStack currently supports the Datadog v2 metrics intake.
use_v3_api:
  series:
    enabled: false

# Пункт назначения трассировок
apm_config:
  enabled: true
  apm_dd_url: "http://localhost:8126"

# Пункт назначения журналов
logs_enabled: true

logs_config:
  logs_dd_url: "http://localhost:8126"
  force_use_http: true

# Для них требуется backend Datadog, который мы не используем, поэтому отключаем их.
remote_updates: false

remote_configuration:
  enabled: false

Эта конфигурация:

Отправляет метрики, трассировки и журналы в приёмник, а не в Datadog.
Отключает приём метрик v3, поскольку ClickStack поддерживает конечную точку метрик Datadog v2.
Отключает удалённые обновления и удалённую конфигурацию, которые зависят от backend Datadog.

Перезапустите агент

Перезапустите агент Datadog, чтобы он подхватил новую конфигурацию. В macOS:

sudo launchctl kickstart -k system/com.datadoghq.agent

Теперь телеметрия от агента поступает в ClickStack, где её можно изучать в HyperDX.

В Open Source ClickStack коллектор защищает свои конечные точки с помощью ключа приёма данных, который создаётся при развертывании стека. Включите приёмник, скопируйте этот ключ из интерфейса ClickStack (HyperDX) и используйте его как ключ API агента Datadog.

Запустите коллектор с включённым приёмником

В примере ниже используется образ «Всё в одном». Если вы используете другую модель дистрибуции, убедитесь, что тот же флаг применён к контейнеру, в котором запущен коллектор.Установите ENABLE_DATADOG_RECEIVER=true и откройте порт 8126:

docker run --name clickstack \
  -p 8080:8080 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 8126:8126 \
  -e ENABLE_DATADOG_RECEIVER=true \
  clickhouse/clickstack-all-in-one:latest

Теперь приёмник доступен по адресу http://localhost:8126.

Запуск локального агента DatadogАгент Datadog также использует порт 8126. Если агент работает на том же хосте, что и коллектор, сопоставьте коллектор с другим портом хоста, чтобы избежать конфликта, например -p 18126:8126, и настройте агент на использование этого порта.

Завершите оставшуюся часть настройки, как описано в руководстве «Начало работы» для версии с открытым исходным кодом.

Скопируйте свой ключ API для приёма данных

В интерфейсе ClickStack (HyperDX) выберите своего пользователя в левом нижнем углу, перейдите в Team Settings > API Keys и скопируйте Ingestion API Key.

Настройте агент Datadog

Обновите файл конфигурации агента /opt/datadog-agent/etc/datadog.yaml, чтобы отправлять журналы, трассировки и метрики в приёмник. Используйте ключ приёма данных ClickStack как ключ API и укажите конечную точку приёмника для каждого пункта назначения:

api_key: "<YOUR_CLICKSTACK_INGESTION_KEY>"

# Пункт назначения для метрик
dd_url: "http://localhost:8126"

# В настоящее время ClickStack поддерживает приём метрик Datadog v2.
use_v3_api:
  series:
    enabled: false

# Пункт назначения для трассировок
apm_config:
  enabled: true
  apm_dd_url: "http://localhost:8126"

# Пункт назначения для журналов
logs_enabled: true

logs_config:
  logs_dd_url: "http://localhost:8126"
  force_use_http: true

# Для этого требуется backend Datadog, который мы не используем, поэтому отключаем эти параметры.
remote_updates: false

remote_configuration:
  enabled: false

Эта конфигурация:

Отправляет метрики, трассировки и журналы в приёмник, а не в Datadog.
Отключает приём метрик v3, поскольку приёмник поддерживает конечную точку метрик Datadog v2.
Отключает удалённые обновления и удалённую конфигурацию, которые зависят от backend Datadog.

Перезапустите агент

Перезапустите агент Datadog, чтобы он применил новую конфигурацию. В macOS:

sudo launchctl kickstart -k system/com.datadoghq.agent

Теперь телеметрия от агента поступает в ClickStack, где вы можете изучать её в HyperDX.

Пошаговый пример

В следующем примере используется демо-приложение, чтобы показать весь путь данных: от инструментированного приложения через агент Datadog в ClickStack.

Клонируйте и запустите демо-приложение

В примере используется демо-приложение Hacker News, инструментированное с помощью Datadog в ветке datadog-instrumentation. Клонируйте эту ветку:

git clone --branch datadog-instrumentation https://github.com/ClickHouse/hn-news-analyzer.git

Чтобы запустить приложение, следуйте инструкциям в README.

Запустите ClickStack с включённым приёмником

Запустите образ «Всё в одном» с включённым приёмником Datadog. Здесь мы пробрасываем приёмник на порт хоста 18126, чтобы избежать конфликта с локальным агентом Datadog, который тоже использует 8126:

docker run --name clickstack \
  -p 8080:8080 \
  -p 8123:8123 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 127.0.0.1:18126:8126 \
  -e ENABLE_DATADOG_RECEIVER=true \
  clickhouse/clickstack-all-in-one:latest

Приёмник будет доступен по адресу http://127.0.0.1:18126.

Установите и настройте агент Datadog

Установите агент Datadog. На macOS:

DD_SITE="datadoghq.com" bash -c "$(curl -L https://install.datadoghq.com/scripts/install_mac_os.sh)"

Обновите /opt/datadog-agent/etc/datadog.yaml, чтобы агент использовал приёмник на порту 18126, а в качестве API key — ваш ключ ингестии ClickStack. Затем перезапустите агент:

sudo launchctl kickstart -k system/com.datadoghq.agent

Полную конфигурацию агента и информацию о том, где найти ключ ингестии, см. в разделе Включение приёмника Datadog.

Изучите телеметрию в ClickStack

Откройте интерфейс HyperDX по адресу http://localhost:8080 и изучите трассировки, журналы и метрики, собранные агентом Datadog.

Что можно мигрировать уже сегодня

Приёмник Datadog — это альфа-компонент OpenTelemetry Collector Contrib, а в дистрибутиве коллектора ClickStack он помечен как экспериментальный, поэтому для его включения требуется feature flag. Приёмник был тщательно протестирован для логов и трассировок и рекомендуется для оценки ClickStack с этими типами сигналов. Метрики работают, но требуют дополнительного тестирования и доработки. В настоящее время приёмник поддерживает конечные точки приёма метрик Datadog v1 и v2, а агенты, использующие более новые версии протокола, нужно явно настроить на отправку метрик через поддерживаемую конечную точку. На данный момент приёмник позволяет быстро оценить ClickStack, если ваши приложения уже используют Datadog SDKs или в вашей инфраструктуре уже работают агенты Datadog. Запустите оба конвейера параллельно, проверьте, как данные представлены и запрашиваются в ClickStack, а затем решите, стоит ли переходить к более масштабной migration. Если оценка покажет явные преимущества, та же архитектура поддерживает постепенную migration: вы сможете сохранить существующую инструментацию Datadog, пока сервисы со временем переходят на OpenTelemetry.

Возможности

Руководства

Миграция с Datadog на ClickStack

Почему стоит запускать ClickStack вместе с Datadog

Как работает приёмник Datadog

Что обрабатывает приёмник

Включение приёмника Datadog

Пошаговый пример

Что можно мигрировать уже сегодня

​Почему стоит запускать ClickStack вместе с Datadog

​Как работает приёмник Datadog

​Что обрабатывает приёмник

​Включение приёмника Datadog

​Пошаговый пример

​Что можно мигрировать уже сегодня

Почему стоит запускать ClickStack вместе с Datadog

Как работает приёмник Datadog

Что обрабатывает приёмник

Включение приёмника Datadog

Пошаговый пример

Что можно мигрировать уже сегодня