Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Движок таблицы FileLog

View as MarkdownEdit this pageReport an issueSet up docs MCP

Этот движок позволяет обрабатывать файлы журнала приложений как поток записей.

FileLog позволяет:

  • Подписываться на файлы журнала.
  • Обрабатывать новые записи по мере их добавления в отслеживаемые файлы журнала.

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

CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
(
    name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1],
    name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2],
    ...
) ENGINE = FileLog('path_to_logs', 'format_name') SETTINGS
    [poll_timeout_ms = 0,]
    [poll_max_batch_size = 0,]
    [max_block_size = 0,]
    [max_threads = 0,]
    [poll_directory_watch_events_backoff_init = 500,]
    [poll_directory_watch_events_backoff_max = 32000,]
    [poll_directory_watch_events_backoff_factor = 2,]
    [handle_error_mode = 'default']

Аргументы движка:

  • path_to_logs – Путь к файлам журнала, которые нужно отслеживать. Это может быть путь к каталогу с файлами журнала или к одному файлу журнала. Обратите внимание, что ClickHouse допускает только пути внутри каталога user_files.
  • format_name - Формат записей. Обратите внимание, что FileLog обрабатывает каждую строку в файле как отдельную запись, поэтому не все форматы данных для этого подходят.

Необязательные параметры:

  • poll_timeout_ms - Тайм-аут одного опроса файла журнала. Значение по умолчанию: stream_poll_timeout_ms.
  • poll_max_batch_size — Максимальное количество записей, считываемых за один опрос. Значение по умолчанию: max_block_size.
  • max_block_size — Максимальный размер батча (в записях) для одного опроса. Значение по умолчанию: max_insert_block_size.
  • max_threads - Максимальное количество потоков для разбора файлов; по умолчанию это 0, что означает, что количество будет равно max(1, physical_cpu_cores / 4).
  • poll_directory_watch_events_backoff_init - Начальное время ожидания для потока наблюдения за каталогом. Значение по умолчанию: 500.
  • poll_directory_watch_events_backoff_max - Максимальное время ожидания для потока наблюдения за каталогом. Значение по умолчанию: 32000.
  • poll_directory_watch_events_backoff_factor - Скорость увеличения задержки; по умолчанию используется экспоненциальный рост. Значение по умолчанию: 2.
  • handle_error_mode — Как обрабатывать ошибки в движке FileLog. Возможные значения: default (если не удастся разобрать сообщение, будет сгенерировано исключение), stream (сообщение об исключении и исходное сообщение будут сохранены в виртуальных столбцах _error и _raw_message).

Описание

Доставленные записи отслеживаются автоматически, поэтому каждая запись в файле журнала учитывается только один раз.

SELECT не слишком полезен для чтения записей (кроме отладки), потому что каждую запись можно прочитать только один раз. Гораздо практичнее создавать потоки в реальном времени с помощью materialized views. Для этого:

  1. Используйте движок, чтобы создать таблицу FileLog, и рассматривайте её как поток данных.
  2. Создайте таблицу с нужной структурой.
  3. Создайте materialized view, которое преобразует данные из движка и помещает их в созданную ранее таблицу.

Когда MATERIALIZED VIEW подключается к движку, оно начинает собирать данные в фоновом режиме. Это позволяет непрерывно получать записи из файлов журнала и преобразовывать их в нужный формат с помощью SELECT. Одна таблица FileLog может иметь сколько угодно materialized views; они не читают данные из таблицы напрямую, а получают новые записи (блоками), поэтому вы можете записывать данные в несколько таблиц с разным уровнем детализации (с группировкой — агрегацией — и без неё).

Пример:

CREATE TABLE logs (
    timestamp UInt64,
    level String,
    message String
  ) ENGINE = FileLog('user_files/my_app/app.log', 'JSONEachRow');

CREATE TABLE daily (
    day Date,
    level String,
    total UInt64
  ) ENGINE = SummingMergeTree
  PARTITION BY toYYYYMM(day)
  ORDER BY (day, level);

CREATE MATERIALIZED VIEW consumer TO daily
    AS SELECT toDate(toDateTime(timestamp)) AS day, level, count() AS total
    FROM logs GROUP BY day, level;

SELECT level, sum(total) FROM daily GROUP BY level;

Чтобы перестать получать данные из потоков или изменить логику преобразования, отсоедините materialized view:

DETACH TABLE consumer;
ATTACH TABLE consumer;

Если вы хотите изменить целевую таблицу с помощью ALTER, рекомендуем отключить materialized view, чтобы избежать расхождений между целевой таблицей и данными представления.

Виртуальные столбцы

  • _filename - Имя файла журнала. Тип данных: LowCardinality(String).
  • _offset - Смещение в файле журнала. Тип данных: UInt64.

Дополнительные виртуальные столбцы при handle_error_mode='stream':

  • _raw_record - Исходная запись, которую не удалось успешно разобрать. Тип данных: Nullable(String).
  • _error - Сообщение об исключении, возникшем при неудачном разборе. Тип данных: Nullable(String).

Примечание: виртуальные столбцы _raw_record и _error заполняются только в случае исключения при разборе; если сообщение было успешно разобрано, они всегда имеют значение NULL.

Navigation