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

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

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

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

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

Чтобы отправлять данные в Управляемый 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 setup
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    compression: gzip
 
  # gRPC setup (alternative)
  otlp/hdx:
    endpoint: 'localhost:4317'
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # Modified as 2 collectors running on same host
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]

Коллектор 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-инструментации следующие конечные точки, предоставляемые 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 setup
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
 
  # gRPC setup (alternative)
  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 # Modified as 2 collectors running on same host
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]