Перейти к основному содержимому
Перейти к основному содержимому

Ингестия данных с помощью Vector

Vector — это высокопроизводительный, независимый от поставщика конвейер данных обсервабилити. Его обычно используют для сбора, трансформации и маршрутизации логов и метрик из широкого спектра источников; он особенно популярен для ингестии логов благодаря своей гибкости и низкому потреблению ресурсов.

При использовании Vector с ClickStack пользователи сами отвечают за определение собственных схем. Эти схемы могут следовать конвенциям OpenTelemetry, но также могут быть полностью произвольными, представляя пользовательские структуры событий. На практике ингестия с помощью Vector чаще всего используется для логов, когда пользователи хотят иметь полный контроль над разбором и обогащением данных до записи в ClickHouse.

Это руководство посвящено подключению данных к ClickStack с использованием Vector как для ClickStack Open Source, так и для Managed ClickStack. Для простоты здесь не рассматриваются источники Vector или конфигурация конвейера в деталях. Вместо этого акцент сделан на конфигурации sink, который записывает данные в ClickHouse, и на обеспечении совместимости результирующей схемы с ClickStack.

Единственное жёсткое требование ClickStack, независимо от того, используется ли open-source-версия или управляемое развертывание, состоит в том, что данные должны содержать столбец с временной меткой (или эквивалентное поле времени), который можно задать при конфигурировании источника данных в интерфейсе ClickStack.

Отправка данных с помощью Vector​


Данное руководство предполагает, что вы уже создали управляемый сервис ClickStack и сохранили учетные данные вашего сервиса. Если вы этого еще не сделали, следуйте руководству Начало работы для управляемого ClickStack до этапа настройки Vector.

Создайте базу данных и таблицу​

Для Vector необходимо определить таблицу и схему до начала ингестии данных.

Сначала создайте базу данных. Это можно сделать с помощью консоли ClickHouse Cloud.

В примере ниже мы используем logs:

CREATE DATABASE IF NOT EXISTS logs

Создайте таблицу для ваших данных. Она должна соответствовать выходной схеме данных. Приведенный ниже пример предполагает классическую структуру Nginx. Адаптируйте её в соответствии с вашими данными, придерживаясь лучших практик для схем. Мы настоятельно рекомендуем ознакомиться с концепцией первичных ключей и выбрать первичный ключ на основе рекомендаций, изложенных здесь.

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)
Первичный ключ Nginx

Указанный выше первичный ключ рассчитан на типичные шаблоны доступа к логам Nginx в интерфейсе ClickStack, но может потребовать корректировки в зависимости от вашей рабочей нагрузки в production-окружении.

Добавьте приёмник ClickHouse в конфигурацию Vector​

Измените конфигурацию Vector, добавив приёмник ClickHouse и обновив поле inputs для приёма событий из существующих конвейеров.

Данная конфигурация предполагает, что ваш upstream-конвейер Vector уже подготовил данные в соответствии с целевой схемой ClickHouse, то есть поля разобраны, корректно именованы и имеют подходящие типы для вставки. См. пример с Nginx ниже для полной иллюстрации разбора и нормализации необработанных строк логов в схему, подходящую для ClickStack.

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"

По умолчанию рекомендуется использовать формат json_each_row, который кодирует каждое событие как отдельный JSON-объект на строку. Это формат по умолчанию и рекомендуемый формат для ClickStack при приёме JSON-данных; его следует предпочесть альтернативным форматам, таким как JSON-объекты, закодированные в виде строк.

Приёмник ClickHouse также поддерживает кодирование потока Arrow (в настоящее время в бета-версии). Это может обеспечить более высокую пропускную способность, но имеет важные ограничения: база данных и таблица должны быть статическими, поскольку схема извлекается один раз при запуске, а динамическая маршрутизация не поддерживается. По этой причине кодирование Arrow лучше всего подходит для фиксированных, чётко определённых конвейеров ингестии.

Рекомендуем ознакомиться с доступными параметрами конфигурации приёмника (sink) в документации Vector:

Примечание

Приведенный выше пример использует пользователя по умолчанию для Managed ClickStack. Для продакшн-развертываний рекомендуется создать выделенного пользователя для ингестии с соответствующими правами и ограничениями.

Перейдите к интерфейсу ClickStack​

Перейдите к управляемому сервису ClickStack и выберите "ClickStack" в меню слева. Если вы уже завершили первоначальную настройку, интерфейс ClickStack откроется в новой вкладке, и вы будете автоматически аутентифицированы. Если нет, пройдите процесс первоначальной настройки и выберите "Launch ClickStack" после выбора Vector в качестве источника данных.

Запустите ClickStack для работы с Vector

Создайте источник данных​

Создайте источник данных для логов. Если источники данных отсутствуют, при первом входе в систему вам будет предложено создать его. В противном случае перейдите в Team Settings и добавьте новый источник данных.

Создать источник данных - Vector

Приведенная выше конфигурация предполагает схему в стиле Nginx со столбцом time_local, используемым в качестве временной метки. По возможности это должен быть столбец временной метки, объявленный в первичном ключе. Данный столбец является обязательным.

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

В приведённом выше примере столбец Body отсутствует в данных. Вместо этого он определяется с помощью SQL-выражения, которое восстанавливает строку журнала Nginx из доступных полей.

Другие доступные параметры см. в справочнике по конфигурации.

Исследование данных​

Перейдите к представлению логов, чтобы изучить данные и начать работу с ClickStack.

Логи Nginx в ClickStack

Пример набора данных с Vector​

В качестве более полного примера ниже мы используем файл журнала Nginx.

В данном руководстве предполагается, что вы уже создали управляемый сервис ClickStack и сохранили учетные данные сервиса. Если нет, следуйте руководству Начало работы для управляемого ClickStack до момента настройки Vector.

Установка Vector​

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

После установки убедитесь, что бинарный файл vector доступен в системном PATH, прежде чем переходить к шагам конфигурации ниже.

Его можно установить на тот же экземпляр, что и ваш ClickStack OTel collector.

Следуйте передовым практикам по архитектуре и безопасности при выводе Vector в продакшн.

Загрузите примеры данных​

Если вы хотите поэкспериментировать с тестовым набором данных, скачайте следующий пример для nginx.

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log
Примечание

Эти данные были собраны с экземпляра Nginx, настроенного на вывод логов в формате JSON для упрощения их разбора. Конфигурацию Nginx для этих логов см. в разделе "Monitoring Nginx Logs with ClickStack".

Создайте базу данных и таблицу​

Для Vector необходимо определить таблицу и схему до начала ингестии данных.

Сначала создайте базу данных. Это можно сделать с помощью консоли ClickHouse Cloud.

Создайте базу данных logs:

CREATE DATABASE IF NOT EXISTS logs

Создайте таблицу для данных.

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)
Первичный ключ Nginx

Приведенный выше первичный ключ рассчитан на типичные шаблоны доступа к логам Nginx в интерфейсе ClickStack, но может потребовать корректировки в зависимости от вашей рабочей нагрузки в production-окружении.

Скопируйте конфигурацию Vector​

Скопируйте конфигурацию Vector и создайте файл nginx.yaml, задав значения CLICKHOUSE_ENDPOINT и CLICKHOUSE_PASSWORD.

data_dir: ./.vector-data
sources:
  nginx_logs:
    type: file
    include:
      - access.log
    read_from: beginning

transforms:
  decode_json:
    type: remap
    inputs:
      - nginx_logs
    source: |
      . = parse_json!(to_string!(.message))
      ts = parse_timestamp!(.time_local, format: "%d/%b/%Y:%H:%M:%S %z")
      # ClickHouse-friendly DateTime format
      .time_local = format_timestamp!(ts, format: "%F %T")

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - decode_json
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"
Примечание

Приведенный выше пример использует пользователя по умолчанию для Managed ClickStack. Для production-развертываний рекомендуется создать выделенного пользователя для ингестии с соответствующими правами доступа и ограничениями.

Запуск Vector​

Запустите Vector следующей командой, предварительно создав каталог данных для записи смещений файлов.

mkdir ./.vector-data
vector --config nginx.yaml

Перейдите в пользовательский интерфейс ClickStack​

Перейдите к управляемому сервису ClickStack и выберите "ClickStack" в меню слева. Если вы уже завершили первоначальную настройку, интерфейс ClickStack откроется в новой вкладке, и вы будете автоматически аутентифицированы. Если нет, пройдите процесс первоначальной настройки и выберите "Launch ClickStack" после выбора Vector в качестве источника данных.

Запустите ClickStack с Vector

Создайте источник данных​

Создайте источник данных для логов. Если источники данных отсутствуют, при первом входе в систему вам будет предложено создать его. В противном случае перейдите в Team Settings и добавьте новый источник данных.

Создать источник данных Vector

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

Мы также указали значение по умолчанию для select: time_local, remote_addr, status, request, что определяет, какие столбцы возвращаются в представлении логов.

В приведённом выше примере столбец Body отсутствует в данных. Вместо этого он определяется как SQL-выражение:

concat(
  remote_addr, ' ',
  remote_user, ' ',
  '[', formatDateTime(time_local, '%d/%b/%Y:%H:%M:%S %z'), '] ',
  '"', request, '" ',
  toString(status), ' ',
  toString(body_bytes_sent), ' ',
  '"', http_referer, '" ',
  '"', http_user_agent, '" ',
  '"', http_x_forwarded_for, '" ',
  toString(request_time), ' ',
  toString(upstream_response_time), ' ',
  '"', http_host, '"'
)

Это восстанавливает строку журнала из структурированных полей.

Другие доступные параметры см. в справочнике по конфигурации.

Исследование данных​

Перейдите в представление поиска за October 20th, 2025, чтобы изучить данные и начать работу с ClickStack.

интерфейс HyperDX