Ингестия через OpenTelemetry

Ингестия данных в ClickStack с помощью OpenTelemetry — стек обсервабилити ClickHouse

Все данные поступают в ClickStack через экземпляр OpenTelemetry (OTel) collector, который служит основной точкой входа для журналов, метрик, трассировок и данных сеансов. Для этого экземпляра мы рекомендуем использовать официальный дистрибутив ClickStack для collector.

Также доступна управляемая версия ClickStack — см. Управляемый ClickStack.

Пользователи отправляют данные в этот collector из language SDKs или через агенты сбора данных, которые собирают инфраструктурные метрики и журналы (например, OTel collector в роли agent или другие технологии, такие как Fluentd или Vector). Для команд, которым нужен управляемый конвейер OpenTelemetry, Bindplane предлагает решение с поддержкой OpenTelemetry и встроенным пунктом назначения ClickStack, упрощая сбор, обработку и маршрутизацию телеметрии.

​

Отправка данных OpenTelemetry

Управляемый ClickStack

​

Установка коллектора ClickStack OpenTelemetry

Чтобы отправлять данные в Управляемый ClickStack, OTel collector следует развернуть в роли шлюза. Инструментирование, совместимое с OTel, будет отправлять события в этот коллектор через OTLP по HTTP или gRPC.

Мы рекомендуем использовать коллектор ClickStack OpenTelemetry

Это позволит вам воспользоваться стандартизированной ингестией, строго заданными схемами и готовой совместимостью с интерфейсом ClickStack (HyperDX). Использование схемы по умолчанию включает автоматическое определение источников и предварительно настроенные сопоставления столбцов.

Дополнительные сведения см. в разделе “Развертывание коллектора”.

​

Отправка данных в коллектор

Чтобы отправлять данные в Управляемый ClickStack, настройте инструментирование OpenTelemetry на следующие конечные точки, предоставляемые OpenTelemetry Collector:

• HTTP (OTLP): http://localhost:4318
• gRPC (OTLP): localhost:4317

Для language SDKs и библиотек телеметрии, поддерживающих OpenTelemetry, вы можете просто задать в приложении переменную окружения OTEL_EXPORTER_OTLP_ENDPOINT:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Если вы разворачиваете дистрибутив contrib для OTel collector в роли agent, можно использовать экспортёр OTLP для отправки данных в коллектор ClickStack. Ниже показан пример конфигурации agent, которая обрабатывает этот структурированный файл журнала.

# clickhouse-agent-config.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-structured.log
    start_at: beginning
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time_local
          layout: '%Y-%m-%d %H:%M:%S'
exporters:
  # Настройка HTTP
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    compression: gzip
 
  # Настройка gRPC (альтернатива)
  otlp/hdx:
    endpoint: 'localhost:4317'
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # Изменено, так как 2 коллектора работают на одном хосте
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]

Open Source ClickStack

Коллектор ClickStack OpenTelemetry входит в состав большинства дистрибутивов ClickStack, включая:

• All-in-One
• Docker Compose
• Helm

​

Установка коллектора ClickStack OpenTelemetry

Коллектор ClickStack OTel также можно развернуть автономно, независимо от других компонентов стека.

Если вы используете дистрибутив HyperDX-only, вы сами отвечаете за доставку данных в ClickHouse. Это можно сделать следующим образом:

• Запустить собственный OpenTelemetry Collector и настроить его на отправку данных в ClickHouse — см. ниже.
• Отправлять данные напрямую в ClickHouse с помощью альтернативных инструментов, таких как Vector, Fluentd и т. д., или даже стандартного дистрибутива OTel contrib collector.

Мы рекомендуем использовать коллектор ClickStack OpenTelemetry

Это позволяет воспользоваться стандартизованной ингестией, принудительно применяемыми схемами и готовой совместимостью с интерфейсом HyperDX. Использование схемы по умолчанию включает автоматическое определение источников и предварительно настроенные сопоставления столбцов.

Подробнее см. в разделе “Развертывание коллектора”.

​

Отправка данных в коллектор

Чтобы отправлять данные в ClickStack, укажите в своей OpenTelemetry-инструментации следующие конечные точки, предоставляемые OpenTelemetry Collector:

• HTTP (OTLP): http://localhost:4318
• gRPC (OTLP): localhost:4317

Для language SDKs и библиотек телеметрии с поддержкой OpenTelemetry вы можете просто задать в приложении переменную окружения OTEL_EXPORTER_OTLP_ENDPOINT:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Кроме того, требуется заголовок авторизации, содержащий ключ API для ингестии ClickStack. Этот ключ можно найти в приложении HyperDX в разделе Team Settings → API Keys.

Для language SDKs это можно задать либо в функции init, либо через переменную окружения OTEL_EXPORTER_OTLP_HEADERS, например:

OTEL_EXPORTER_OTLP_HEADERS='authorization=<YOUR_INGESTION_API_KEY>'

Агенты также должны включать этот заголовок Authorization в любой обмен по OTLP. Например, при развертывании contrib-дистрибутива OTel collector в роли агента можно использовать экспортер OTLP. Ниже показан пример конфигурации агента, использующего этот структурированный файл журнала. Обратите внимание, что необходимо указать ключ авторизации — см. <YOUR_API_INGESTION_KEY>.

# clickhouse-agent-config.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-structured.log
    start_at: beginning
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time_local
          layout: '%Y-%m-%d %H:%M:%S'
exporters:
  # Настройка HTTP
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
 
  # Настройка gRPC (альтернативный вариант)
  otlp/hdx:
    endpoint: 'localhost:4317'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # Изменено, так как 2 коллектора работают на одном хосте
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]