Журналы¶

Настройка уровня событий¶

Параметр level указывает уровень событий, которые должны быть записаны в журнал. Параметр может принимать следующие значения:

• trace, наиболее детальный уровень записи, часто чрезвычайно подробная информация.

• debug, запись информации с низким приоритетом;

• info, запись полезной информации;

• warn, запись информации о потенциально опасных событиях;

• error, запись информации о серьезных ошибках.

В таблице ниже перечислены события, соответствующее им значение параметра level («уровень») и краткое описание:

Настройка места сохранения журналов¶

События аудита могут записываться, в зависимости от конфигурации, как в syslog, так и в файл. Конфигурация производится отдельно для экземпляров Scheduler и Storage, например:

audit_log:
  level: trace
  writer:
    type: syslog

Параметр writer указывает на то, куда будут сохраняться события: в журнал Syslog (type: syslog) или в файл (type: file).

При сохранении в файл необходимо указать также директорию и префикс имени файла:

audit_log:
  level: trace
  writer:
    type: file
    directory: ./logs/
    filename_prefix: audit_log

При конфигурации type: file события аудита хранятся на диске в указанной директории, где каждый час создается новый файл с именем вида audit_log.2025-09-08-11.jsonl.

При конфигурации type: syslog записи можно посмотреть с помощью journalctl, например:

journalctl -t tcs-audit

Записи доступны в формате JSON. Пример записей:

{"timestamp":"2025-09-01T11:31:45.708258Z","level":"INFO","user":"tcs","stmt_name":"query","args":"1","target":"audit"}
{"timestamp":"2025-09-01T11:31:45.708775Z","level":"INFO","user":"tcs","table_ref":"datafusion.public.attributes","target":"audit"}
{"timestamp":"2025-09-01T11:37:00.070271Z","level":"INFO","message":"record insert","user":"test_user","table_ref":"test","target":"audit"}
{"timestamp":"2025-09-01T11:37:42.926327Z","level":"INFO","message":"prepared execution","user":"tcs","stmt_name":"query","args":"1","target":"audit"}
{"timestamp":"2025-09-01T11:37:42.926595Z","level":"INFO","message":"table_scan","user":"tcs","table_ref":"datafusion.public.attributes","target":"audit"}

Настройка мест сохранения журналов¶

Параметр target указывает место записи событий системных журналов: стандартный вывод (target: stdout), журнал Syslog (target: syslog), или файл (target: file).

При необходимости можно включить и настроить все виды записи одновременно.

Конфигурация производится:

• на корневом уровне конфигурации Scheduler;

• в конфигурации ролей Tarantool для Storage.

Пример конфигурации:

log:
  - target: stdout
    level: ERROR
  - target: syslog
    protocol: unix
    path: /dev/log
    level: DEBUG
  - target: file
    level: ERROR
    format: compact
    path: errors.log

Если не указывать секцию log на экземпляре, то для него система будет вести себя эквивалентно настройке:

log:
  - target: stdout
    level: INFO

Для каждого места записи можно определить параметры level и format.

Для журнала Syslog (target: syslog) дополнительно необходимо указать тип протокола (protocol):

• udp;

• tcp;

• unix. При выборе этого протокола также необходимо указать путь к файлу Unix-сокета при помощи параметра path.

Для записи событий в файл (target: file) необходимо указать путь к файлу для записи при помощи параметра path.

Настройка уровня событий¶

Параметр level указывает уровень событий, которые должны быть записаны в журнал. Параметр не чувствителен к регистру и может принимать следующие значения:

• TRACE, наиболее детальный уровень записи, часто чрезвычайно подробная информация.

• DEBUG, запись информации с низким приоритетом;

• INFO, запись полезной информации, значение по умолчанию;

• WARN, запись информации о потенциально опасных событиях;

• ERROR, запись информации о серьезных ошибках.

Настройка формата записи¶

Параметр format указывает формат, в котором будут сохраняться события:

• plain, значение по умолчанию;

• compact;

• json.

Настройка по модулям¶

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

Настройка производится с помощью параметра конфигурации per_module, внутри которого можно перечислить пары значений вида <модуль>: <уровень>.

В качестве значения <модуль> можно указывать полный иерархический путь до модуля, либо префикс такого пути. Путь до модуля (например, aggregator::runtimes или h2::codec::framed_write) можно узнать одним из следующих способов:

• От сотрудника VK Tech в случае совместной работы (например, при разборе причин определенного поведения).

• Из уже имеющихся журналов. В каждой записи журнала есть информация о модуле, для которого она была сделана, и об уровне этой записи. Например:

  Запись в формате JSON (здесь в поле target указан путь до модуля aggregator::storage::record_buffer::flushing):

  {"timestamp":"2026-03-20 08:06:59.602","level":"INFO","fields":{"message":"got readview for flushing; getting record buffer block"},"target":"aggregator::storage::record_buffer::flushing"}
  

  Запись в формате COMPACT (здесь указан путь до модуля aggregator::storage::record_buffer::flushing):

  2026-03-20 14:29:03.058  INFO aggregator::storage::record_buffer::flushing: got readview for flushing; getting record buffer block
  

  Запись в формате PLAIN (здесь указан путь до модуля h2::codec::framed_write):

  2026-03-20 14:29:03.077 DEBUG Connection{peer=Client}: h2::codec::framed_write: send frame=WindowUpdate { stream_id: StreamId(0), size_increment: 5177345 }
  

В качестве значения <уровень> можно указывать одно из значений параметра level.

Каждая такая пара <модуль>: <уровень> переопределяет уровень журналирования для указанного модуля и его подмодулей.

Пример конфигурации:

- target: stdout
  level: INFO
  format: plain
  per_module:
    module_a: DEBUG
    module_b: WARN

В этом примере в stdout будут попадать записи уровня не выше INFO из всех модулей, кроме module_b – оттуда будут попадать только записи уровнем не выше WARN.

В то же время из модуля module_a дополнительно будут попадать записи уровня DEBUG.

Настройка по спанам¶

Спан (span) – это логический объект, соответствующий определенному участку исходного кода. Спаны используются для диагностики поведения приложения, чаще всего как компоненты более сложных структур (см. спецификацию OpenTracing или OpenTelemetry). Порядок создания и существования каждого спана определяется участком исходного кода, которому он соответствует. Спан содержит, помимо прочего, информацию о длительности исполнения этого участка кода.

Включить журналирование по спанам можно с помощью параметра конфигурации log_span_bounds. Если указано значение true, то в журналы попадают записи о моментах входа и закрытия спанов. По умолчанию используется значение false (журналирование по спанам отключено).

Пример конфигурации:

- target: file
  path: "/var/log/app.log"
  level: DEBUG
  format: json
  log_span_bounds: true

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

Пример записи о входе в спан (enter) и его закрытии (close):

• в формате PLAIN:

  2026-03-24 10:11:18.927 DEBUG resolve{host=localhost}: hyper_util::client::legacy::connect::dns: enter
  2026-03-24 10:11:18.927 DEBUG resolve{host=localhost}: hyper_util::client::legacy::connect::dns: close time.busy=186µs time.idle=448µs
  

• в формате JSON:

  {"timestamp":"2026-03-24 10:12:09.922","level":"DEBUG","fields":{"message":"enter"},"target":"hyper_util::client::legacy::connect::dns","span":{"host":"localhost","name":"resolve"},"spans":[{"host":"localhost","name":"resolve"}]}
  {"timestamp":"2026-03-24 10:12:09.922","level":"DEBUG","fields":{"message":"close","time.busy":"188µs","time.idle":"285µs"},"target":"hyper_util::client::legacy::connect::dns","span":{"host":"localhost","name":"resolve"},"spans":[]}