Отправка OpenTelemetry в ClickStack с помощью Odigos

Partner Integration

Кратко

В этом руководстве показано, как экспортировать телеметрию Odigos в ClickStack. Вы узнаете, как:

Развернуть Odigos в Kubernetes с помощью Helm
Добавить источники в интерфейсе Odigos
Добавить пункт назначения OTLP HTTP, указывающий на ClickStack
Проверить журналы, метрики и трассировки в ClickStack

Odigos автоматически добавляет инструментацию в приложения без изменения кода и перезапуска; ClickStack хранит данные в ClickHouse и позволяет выполнять по ним запросы.

Требуемое время: 10–20 минут

Что такое Odigos?

Odigos — это плоскость управления инструментированием для Kubernetes и виртуальных машин, которая инструментирует приложения на уровне ядра с помощью eBPF. Поскольку сбор выполняется в ядре, накладные расходы на приложение остаются низкими, а наблюдаемость — высокой. Вы получаете OpenTelemetry-трассировки, метрики, журналы и профили промышленного уровня без внедрения новых агентов в прикладной код и без ожидания обновлений библиотек во всех сервисах.

Именно этот слой eBPF делает возможной глубокую и согласованную телеметрию в большом масштабе. Odigos может автоматически включать и отключать более глубокое инструментирование, когда это нужно, чтобы упростить отладку и устранение проблем:

Контекст на уровне кода — атрибуты, связанные с функциями и поведением среды выполнения
HTTP-трафик — запросы и ответы между вашими сервисами
Системы обмена сообщениями — полезная нагрузка и сообщения из Kafka и аналогичных брокеров
Подробная информация об ошибках — трассировки стека при сбоях
Пользовательское инструментирование — расширяйте покрытие там, где автоинструментирование уже не справляется, без изменений кода и перезапусков

За кулисами Odigos создает и управляет полноценным конвейером OpenTelemetry для вашего кластера: коллекторами, которые масштабируются вместе с нагрузкой, маршрутизацией в выбранные вами целевые системы и логикой конвейера, которой вы управляете через интерфейс. Настройте сэмплирование для управления объемом, маскирование PII для исключения конфиденциальных данных из экспорта и правила OTTL для фильтрации, преобразования или обогащения телеметрии до того, как она покинет кластер.

Почему Odigos + ClickStack?

Развертывание OpenTelemetry в большом количестве сервисов часто занимает много времени и даёт лишь поверхностную наблюдаемость приложений. Odigos выполняет eBPF-инструментирование для более глубокой телеметрии и управляет работой коллекторов в Kubernetes; ClickStack предоставляет хранилище на базе ClickHouse и интерфейс HyperDX для выполнения запросов к телеметрии в масштабе.

Ключевые выводы

Odigos автоматически добавляет инструментирование для любой рабочей нагрузки Kubernetes без необходимости перезапуска и автоматически управляет конвейерами OpenTelemetry.
ClickStack хранит журналы, метрики и трассировки в ClickHouse и отображает их в HyperDX.

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

ClickStack установлен и доступен из вашего кластера Kubernetes. См. Начало работы с ClickStack с открытым исходным кодом или Начало работы с Управляемым ClickStack.
Ваша HTTP-конечная точка OTLP ClickStack (порт 4318) и значение для аутентификации, которое Odigos будет передавать в заголовке Authorization. Для ClickStack с открытым исходным кодом это ключ API для ингестии ClickStack из Team Settings → API Keys в интерфейсе HyperDX. Для Управляемого ClickStack это OTLP_AUTH_TOKEN, который вы задаёте при запуске собственного автономного коллектора ClickStack.
Кластер Kubernetes (узлы Linux с ядром 4.18 или новее для инструментирования eBPF)
Helm, kubectl и учётные данные для доступа к кластеру, чтобы выполнить установку в пространство имен odigos-system
On-prem-токен Odigos Enterprise — обратитесь к команде Odigos для получения доступа

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

Развёртывание Odigos с помощью Helm

Odigos Enterprise требует лицензионный токен для локального развёртывания. Экспортируйте его в оболочке:

export ODIGOS_ONPREM_TOKEN="<your-enterprise-token>"

Кроме того, можно сохранить токен в Kubernetes Secret с именем odigos-pro перед установкой. См. Установка Odigos Enterprise.

Добавьте Helm-репозиторий Odigos и установите чарт в odigos-system:

helm repo add odigos https://odigos-io.github.io/odigos/
helm repo update

helm upgrade --install odigos odigos/odigos \
  --namespace odigos-system \
  --create-namespace \
  --set onPremToken=$ODIGOS_ONPREM_TOKEN

Дополнительные переопределения конфигурации можно передать с помощью флагов --set или пользовательского файла значений (-f). Значения по умолчанию для чарта находятся в файле helm/odigos/values.yaml на GitHub.

Убедитесь, что поды Odigos запущены:

kubectl get pods -n odigos-system

Добавление источников в интерфейсе Odigos

Пробросьте порт сервиса интерфейса Odigos:

kubectl port-forward svc/ui -n odigos-system 3000:3000

Откройте http://localhost:3000 в своем браузере.
Перейдите в раздел Sources и выберите пространства имен или рабочие нагрузки, которые хотите инструментировать.
Нажмите кнопку Done внизу, когда отметите все рабочие нагрузки для инструментирования.
Убедитесь, что в столбце Sources рабочие нагрузки успешно инструментированы.

Добавление ClickStack в качестве пункта назначения в интерфейсе Odigos

Чтобы отправлять телеметрию в ClickStack, добавьте пункт назначения OTLP HTTP в Odigos. Конкретная конфигурация зависит от способа развёртывания ClickStack. В версии ClickStack с открытым исходным кодом OpenTelemetry Collector поставляется в комплекте, а ключ ингестии автоматически генерируется в интерфейсе HyperDX. При использовании Управляемого ClickStack вы запускаете собственный автономный коллектор ClickStack и самостоятельно задаёте токен аутентификации при запуске контейнера.

Альтернатива: запись напрямую в ClickHouse

Если ClickHouse доступен из вашего кластера Kubernetes, можно полностью пропустить OTLP-коллектор и использовать вместо него нативный пункт назначения ClickHouse в Odigos. Это работает как для версии с открытым исходным кодом, так и для Управляемого ClickStack.

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

В ClickStack с открытым исходным кодом, например в образе all-in-one, OpenTelemetry Collector, работающий как шлюз, уже включён, а ключ API для ингестии ClickStack HyperDX генерирует автоматически.

В интерфейсе Odigos нажмите Add Destination и выберите OTLP HTTP.
В поле OTLP HTTP Endpoint укажите конечную точку коллектора ClickStack (например, http://clickstack.example.com:4318). Подробнее о конечной точке см. в разделе Ingesting with OpenTelemetry.
Скопируйте ключ API для ингестии ClickStack в интерфейсе ClickStack из раздела Team Settings → API Keys.
В разделе Headers добавьте:
- Key: Authorization
- Value: ваш ключ API для ингестии ClickStack
Включите Logs, Metrics и Traces.
Сохраните пункт назначения.

Управляемый ClickStack не включает размещённый OpenTelemetry Collector и не отображает ключ ингестии в интерфейсе. Вместо этого вам нужно самостоятельно запустить дистрибутив коллектора ClickStack в автономном режиме и при запуске контейнера задать токен аутентификации через переменную окружения OTLP_AUTH_TOKEN. После этого Odigos будет отправлять OTLP HTTP-трафик в этот коллектор, передавая тот же токен в заголовке Authorization.

Запустите коллектор ClickStack в автономном режиме, указав ваш сервис ClickHouse Cloud и защитив его с помощью 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 \
  -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 \
  clickhouse/clickstack-otel-collector:latest

Рекомендации по TLS, выделенным пользователям для ингестии и другим аспектам production-среды см. в разделе Securing the collector.

В интерфейсе Odigos нажмите Add Destination и выберите OTLP HTTP.
В поле OTLP HTTP Endpoint укажите конечную точку автономного коллектора, который вы только что запустили (например, http://my-collector.example.com:4318).
В разделе Headers добавьте:
- Key: Authorization
- Value: значение OTLP_AUTH_TOKEN, которое вы задали для коллектора
Включите Logs, Metrics и Traces.
Сохраните пункт назначения.

Необязательно: манифест Kubernetes

Тот же пункт назначения можно настроить с помощью манифеста Destination вместо интерфейса. См. раздел Configure destinations with Kubernetes manifests в Advanced configuration.

Проверка телеметрии в ClickStack

Откройте интерфейс ClickStack (HyperDX):
- ClickStack с открытым исходным кодом: например, http://<host>:8080 в образе all-in-one.
- Управляемый ClickStack: откройте свой сервис в консоли ClickHouse Cloud, затем нажмите Launch ClickStack. Подробности см. в разделе Переход к интерфейсу ClickStack.
Проверьте, появились ли в журналах, метриках и трассировках данные из ваших инструментированных сервисов.
Отфильтруйте трассировки по odigos.version, чтобы проверить сквозную передачу данных.

Если данные отсутствуют, проверьте журналы коллектора: kubectl logs deploy/odigos-gateway -n odigos-system

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

Нормализатор логов HyperDX

Если вы экспортируете данные напрямую в ClickHouse с помощью собственного пункта назначения ClickHouse в Odigos (вместо OTLP HTTP в ClickStack), включите нормализатор логов HyperDX (HYPERDX_LOG_NORMALIZER: true). Он разбирает JSON в теле логов и нормализует атрибуты, чтобы упростить выполнение запросов в интерфейсе ClickStack.

Нативный пункт назначения ClickHouse

Если ClickHouse доступен напрямую из вашего кластера, вы можете использовать нативный пункт назначения ClickHouse в Odigos вместо OTLP HTTP. Настройте конечную точку ClickHouse, имя базы данных и параметры схемы в интерфейсе или с помощью манифеста — см. пункт назначения ClickHouse в Odigos.

Схема для продакшена: Установите CLICKHOUSE_CREATE_SCHEME в false и примените собственный DDL.
TLS / аутентификация: Используйте CLICKHOUSE_TLS_ENABLED, CLICKHOUSE_USERNAME и Kubernetes Secret для хранения пароля.

Настройка пунктов назначения с помощью манифестов Kubernetes

OTLP HTTP (ClickStack)

apiVersion: odigos.io/v1alpha1
kind: Destination
metadata:
  name: clickstack
  namespace: odigos-system
spec:
  type: otlphttp
  destinationName: otlphttp
  signals:
    - TRACES
    - METRICS
    - LOGS
  data:
    OTLP_HTTP_ENDPOINT: 'http://clickstack.example.com:4318'
    # API ingestion key for open source ClickStack, or OTLP_AUTH_TOKEN for Managed ClickStack
    OTLP_HTTP_HEADERS: 'Authorization:<YOUR_AUTHORIZATION_VALUE>'

ClickHouse (напрямую)

apiVersion: odigos.io/v1alpha1
kind: Destination
metadata:
  name: clickhouse
  namespace: odigos-system
spec:
  type: clickhouse
  destinationName: clickhouse
  signals:
    - TRACES
    - METRICS
    - LOGS
  data:
    CLICKHOUSE_ENDPOINT: 'http://clickstack.example.com:8123'
    CLICKHOUSE_DATABASE_NAME: 'otel'
    CLICKHOUSE_CREATE_SCHEME: 'true'

Примените манифест:

kubectl apply -f destination.yaml

VM-агент Odigos

Odigos VM Agent выполняет инструментацию процессов Linux, сервисов systemd и/или контейнеров Docker с помощью eBPF. Телеметрия экспортируется в те же пункты назначения, что и в кластерной версии Odigos, включая ClickStack через OTLP HTTP.

VM Agent входит в состав Odigos Pro. Сведения о настройке, источниках и конфигурации пунктов назначения см. в обзоре VM Agent.

Odigos Central

Odigos Central — это централизованная плоскость управления, которая позволяет из одного интерфейса управлять инструментированием, пунктами назначения и конфигурацией конвейеров сразу в нескольких кластерах Kubernetes, вместо того чтобы настраивать каждый кластер по отдельности.

Odigos Central доступен в Odigos Enterprise. Подробнее об управлении несколькими кластерами, SSO и единых правилах сэмплирования см. в обзоре Odigos Central.

Следующие шаги

Анализируйте трассировки для инструментированных сервисов в ClickStack
Создавайте панели мониторинга для метрик, экспортируемых Odigos
Настройте схему ClickHouse и TTL с учетом ваших требований к хранению данных и шаблонов запросов

Что такое Odigos?​

Почему Odigos + ClickStack?​

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

Интеграция ClickStack с Odigos​

Развёртывание Odigos с помощью Helm​

Добавление источников в интерфейсе Odigos​

Добавление ClickStack в качестве пункта назначения в интерфейсе Odigos​

Проверка телеметрии в ClickStack​

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

Нормализатор логов HyperDX​

Нативный пункт назначения ClickHouse​

Настройка пунктов назначения с помощью манифестов Kubernetes​

VM-агент Odigos​

Odigos Central​

Следующие шаги​

Читайте также​