Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

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

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

Отправка данных через Vector


В данном руководстве предполагается, что вы уже создали сервис Управляемого ClickStack и сохранили учётные данные сервиса. Если нет, следуйте руководству Getting Started для Управляемого 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)

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

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

Эта конфигурация предполагает, что предшествующий конвейер 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, закодированными в виде строк.

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

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

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

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

Создание источника данных — vector

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

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

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

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

Просмотрите данные

Перейдите в представление журналов, чтобы просмотреть данные и начать работу с ClickStack.

Журналы Nginx в ClickStack

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

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

В данном руководстве предполагается, что вы уже создали сервис Управляемого ClickStack и сохранили учётные данные сервиса. Если нет, следуйте руководству Getting Started для Управляемого 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

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

Для 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)

Скопируйте конфигурацию 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>"

Запуск Vector

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

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

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

Создайте источник данных для журналов. Если источников данных ещё нет, при первом входе в систему вам будет предложено создать его. В противном случае перейдите в 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
Navigation