MorphCluster Logger

Подсистема логирования состоит из двух пакетов:

• @morphcluster/logger — серверная часть, предоставляющая сервисы для сбора, хранения и администрирования логов.
• @morphcluster/logger-client — клиентский бэкенд для Logger из ядра, обеспечивающий передачу логов на сервер логирования.

Серверная часть (@morphcluster/logger)

Пакет регистрирует в ServiceHost четыре сервиса: LogStoreBackend, LogStoreAdmin, LogOraList и вспомогательный PostgresMigrator (из отдельного пакета). Основное хранилище — PostgreSQL, взаимодействие с которым вынесено в сервис LogPgStorage2.

LogStoreBackend

Главный сервис приёма логов. Реализует два запроса: write и close. Полученные данные не пишутся в базу сразу, а накапливаются в оперативной памяти в виде дерева объектов LogRecord (класс ActiveLogs). При закрытии корневого лога вся ветка отправляется в LogPgStorage2.insertLogTree().

// Пример использования (происходит автоматически при подключении LoggerBackendStore)
await logStoreBackend.write({ id, parentId, message, level, ... });
await logStoreBackend.close({ id, timestamp });

Жизненный цикл активного лога:

1. Клиент вызывает write при создании лога и для каждого дочернего сообщения.
2. Сообщения собираются в древовидную структуру LogRecord внутри ActiveLogs.
3. Когда клиент вызывает close для записи (или по тайм-ауту), ActiveLogs проверяет, все ли дочерние записи закрыты. Если да — вся ветка помечается на архивацию и через 5 секунд (flushLogTime) вызывается onArchive, передающий корневой LogRecord в LogPgStorage2.
4. LogPgStorage2 вставляет всё дерево одной массовой вставкой в таблицу logs2.

Свойства и зависимости:

• LogPgStorage2 — обязательный сервис для работы с БД.
• RegistryHelper — для получения настроек логирования из общего реестра (minLevel, maxRecords).
• activeLogs: ActiveLogs — хранилище незавершённых логов.

LogRecord

Модель одной записи лога. Образует древовидную структуру: родитель (parent) и массив дочерних записей (children).

const record = new LogRecord({
  id: 'uuid',
  message: 'Запрос выполнен',
  level: 3,
  service: 'MyService',
  payload: { ... }
});
record.addChild(childRecord);

Основные поля:

• id, message, level, host, service, username, ip
• payload — произвольные данные
• order — порядок среди дочерних одного родителя
• duration — длительность (заполняется при закрытии)
• timestamp — временная метка
• closed — флаг завершения записи
• parent / children — связи дерева
• serverTimestamp — момент попадания на сервер (для детекта зависших логов)
• dontArchive — если true, запись не будет сохранена в БД (например, автоматически созданный родитель «Unknown Parent»).

Методы:

• addChild(record) — добавить дочернюю запись (только если текущая ещё не закрыта).
• levelToRoot() — протолкнуть максимальный уровень вверх по дереву до корня.
• findRecordById(id) — рекурсивный поиск записи по идентификатору.
• getPath() — путь от корня до текущей записи.
• getRoot() — корневая запись.
• sortChildren() — сортировка детей по order (рекурсивно).
• getJson() — сериализация всего поддерева в объект (для ответа API).
• forEach(callback) — обход всех узлов дерева в ширину.

ActiveLogs

Хранилище всех активных (ещё не заархивированных) записей в памяти. Управляет их жизненным циклом: вставка, закрытие, автоматическое закрытие по тайм-ауту, архивация.

const activeLogs = new ActiveLogs();
activeLogs.onArchive = (rootLog) => { /* сохранить в БД */ };
activeLogs.insert({ id: '...', message: 'Старт' });
activeLogs.close('id', Date.now());

Основные методы и логика:

• insert(request) — создаёт или обновляет LogRecord.
  • Если передан parentId, находит или создаёт родителя. При отсутствии реального родителя создаётся запись-заглушка с dontArchive = true и сообщением 'Unknown Parent'.
  • Вызывает levelToRoot() для подъёма уровня.
  • Обрабатывает ситуацию, когда close пришёл раньше write (через очередь unknownCloses).
• close(id, timestamp) — закрывает запись. Если запись ещё не известна, сохраняет «закрытие» в unknownCloses на 10 секунд, ожидая появления записи. После закрытия рекурсивно проверяет родительские ветки (checkBranch); если корень полностью закрыт, запускает таймер (5 секунд), после которого ветка удаляется из памяти и передаётся в onArchive.
• checkTimeouts() — периодическая проверка (каждую секунду):
  • Закрытые ветки, готовые к архивации, отправляются в onArchive.
  • Неиспользованные unknownCloses удаляются через 10 секунд.
  • Незакрытые логи, неактивные более 15 минут (autoCloseTime), автоматически закрываются с уровнем 50 и сообщением 'Log Timeout'.
• removeBranch(curLog) — удаляет всё поддерево из logsPlain.
• getRootLogs() — возвращает только корневые логи (для listActive).

Свойства:

• logsPlain — плоский массив всех известных записей (и корневых, и дочерних).
• unknownCloses — очередь «закрытий», ожидающих свои записи.
• onArchive — колбэк, вызываемый при готовности корневого лога к сохранению.

LogPgStorage2

Сервис для взаимодействия с PostgreSQL. Выполняет миграции, создаёт пул соединений, вставляет деревья логов, предоставляет методы для чтения и очистки.

await logPgStorage2.insertLogTree(rootLogRecord);
const result = await logPgStorage2.list({ service: 'MyService', limit: 20 });
const log = await logPgStorage2.byId('uuid');

Управление:

• minLevel: number — логи с уровнем ниже не сохраняются (по умолчанию 0, берётся из реестра).
• maxRecords: number — после вставки, если счётчик корневых записей превышает лимит, вызывается cleanup() (полная очистка таблицы). Значение по умолчанию 500.
• recordsCount — текущее количество корневых записей.

Методы:

• insertLogTree(rootLog) — рекурсивно обходит дерево, собирает массив записей для вставки. Игнорирует записи с level < minLevel. Выполняет массовый INSERT. При дубликате id корневого лога переименовывает его, генерирует новый id и ставит уровень 50.
• list(request) — выборка корневых логов с фильтрацией (service, username, minLevel, dateFrom/dateTo и др.) и пагинацией.
• listChildren(parentId) / listChildrenRecursive(parentId) — получение дочерних записей.
• byId(logId) — одна запись по идентификатору.
• cleanup() — TRUNCATE таблицы.
• tableSize() — размер таблицы в человекочитаемом виде.
• serviceOptions() — список уникальных сервисов, встречающихся в логах.
• start(log) — инициализирует миграции, создаёт пул соединений, проверяет подключение (PGTest) и считает количество корневых записей.

Схема БД (подразумевается): таблица logs2 с колонками id, parent_id, message, level, duration, timestamp, order, host, service, username, ip, created, payload, num (автоинкрементный номер для курсорной пагинации).

LogStoreAdmin

Сервис для административного доступа к логам. Все запросы требуют прав администратора (needAdmin: true).

Запросы:

• list(request) — делегирует в LogPgStorage2.list.
• listActive(req) — возвращает текущие незавершённые корневые логи из activeLogs. Поддерживает фильтрацию по minLevel и service.
• details(request) — сначала ищет лог в активных (activeLogs), если не найден — загружает из базы с рекурсивными дочерними записями.
• stats — возвращает recordsCount и размер таблицы.
• cleanup — принудительная очистка таблицы логов.
• serviceOptions — делегирует в LogPgStorage2.

Зависимости: LogStoreBackend, LogPgStorage2.

LogOraList

Специализированное представление для получения логов запросов к Oracle (тип сообщения 'OraQueries/exec' или 'OraQueries/execFunc'). Извлекает из древовидной структуры входные и выходные параметры, собирая их из фиксированной иерархии дочерних записей (4 уровня вложенности). Возвращает плоский список с полями queryName, duration, in_payload, out_payload.

Запрос:

• list(filter) — filter может содержать username, payload (поиск по тексту во входном payload), minLevel, minDuration, dateFrom/dateTo, плюс стандартные limit и offset.

Схемы сервисов

• LogStoreBackend — два внутренних запроса write и close (не требуют аутентификации, не логируются сами).
• LogStoreAdmin — запросы list, listActive, details, serviceOptions, stats, cleanup (требуют прав администратора).
• LogOraList — запрос list с фильтром.

Клиентская часть (@morphcluster/logger-client)

LoggerBackendStore

Реализация бэкенда LoggerBackend из ядра, которая отправляет все логи на серверный LogStoreBackend. Обеспечивает прозрачную буферизацию логов до момента появления сервиса логирования в хосте.

import { LoggerBackendStore } from '@morphcluster/logger-client';

const logStoreBackend = new LoggerBackendStore(host);
logger.backends.push(logStoreBackend);

Принцип работы:

1. При создании получает ссылку на ServiceHost и подписывается на событие onServiceStarted.
2. Как только в хосте появляется сервис с именем LogStoreBackend (или LogStoreAcc, если есть), он сохраняет ссылку на него.
3. До этого момента все вызовы write и close помещаются в очередь (queue).
4. При обнаружении сервиса очередь «сбрасывается» — все накопленные операции последовательно отправляются в реальный сервис. После этого flushed устанавливается в true, и дальнейшие вызовы выполняются напрямую, без очереди.

Таким образом, логирование не теряется даже на этапе запуска приложения, когда сервис логирования ещё не готов.

Свойства:

• host: ServiceHost
• LogStore — ссылка на обнаруженный сервис (например, LogStoreBackend).
• queue: Array — очередь отложенных вызовов { method, data, resolve, reject }.
• flushed: boolean — флаг завершения «слива» очереди.

Взаимодействие компонентов

1. Сервис приложения использует обычный Logger из ядра, добавив в него бэкенд LoggerBackendStore.
2. LoggerBackendStore отправляет запросы write и close в локальный или удалённый LogStoreBackend (через GlobalService).
3. LogStoreBackend сохраняет все записи в ActiveLogs в оперативной памяти.
4. Когда ветка лога полностью закрыта, ActiveLogs вызывает LogPgStorage2.insertLogTree(), который одной массовой вставкой записывает всё дерево в PostgreSQL.
5. Для чтения логов используются сервисы LogStoreAdmin (универсальный) и LogOraList (специализированный для Oracle-запросов). Они читают данные напрямую из ActiveLogs (активные) и из LogPgStorage2 (архивные).

Такая архитектура минимизирует количество обращений к базе данных и позволяет гибко настраивать уровни логирования через центральный реестр.