#Логирование

NocoBase предоставляет высокопроизводительную систему логирования на базе pino. В любом месте, где доступен context, вы можете получить экземпляр логгера через ctx.logger и записывать ключевые события во время работы плагина или системы.

#Базовое использование

// Логирование фатальных ошибок (например, сбой инициализации)
ctx.logger.fatal('Application initialization failed', { error });

// Логирование обычных ошибок (например, ошибок API-запросов)
ctx.logger.error('Data loading failed', { status, message });

// Логирование предупреждений (например, рисков производительности или исключений действий пользователя)
ctx.logger.warn('Current form contains unsaved changes');

// Логирование общей информации времени выполнения (например, компонент загружен)
ctx.logger.info('User profile component loaded');

// Логирование отладочной информации (например, изменения состояния)
ctx.logger.debug('Current user state', { user });

// Логирование подробной трассировки (например, процесса рендера)
ctx.logger.trace('Component rendered', { component: 'UserProfile' });

Эти методы соответствуют разным уровням логирования (от высокого к низкому):

#Формат логов

Каждая запись лога выводится в структурированном формате JSON и по умолчанию содержит следующие поля:

Пример вывода:

{
  "level": 30,
  "time": 1730540153064,
  "pid": 12765,
  "hostname": "nocobase.local",
  "msg": "HelloModel rendered",
  "a": "a"
}

#Привязка контекста

ctx.logger автоматически добавляет контекстную информацию, такую как текущий плагин, модуль или источник запроса, что позволяет точнее отслеживать происхождение логов.

plugin.context.logger.info('Plugin initialized');
model.context.logger.error('Model validation failed', { model: 'User' });

Пример вывода (с контекстом):

{
  "level": 30,
  "msg": "Plugin initialized",
  "plugin": "plugin-audit-trail"
}

#Пользовательский логгер

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

const logger = ctx.logger.child({ module: 'MyPlugin' });
logger.info('Submodule started');

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

#Иерархия уровней логирования

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

Pino выводит только логи, уровень которых больше или равен текущей конфигурации level. Например, если установлен уровень info, логи debug и trace будут игнорироваться.

#Лучшие практики в разработке плагинов

1. Используйте контекстный логгер
   Используйте ctx.logger в контексте плагина, модели или приложения, чтобы автоматически добавлять информацию об источнике.

2. Разделяйте уровни логирования

   • Используйте error для записи бизнес-исключений
   • Используйте info для записи изменений состояния
   • Используйте debug для отладочной информации на этапе разработки

3. Избегайте избыточного логирования
   Особенно для уровней debug и trace: рекомендуется включать их только в среде разработки.

4. Используйте структурированные данные
   Передавайте параметры в виде объектов вместо конкатенации строк — это упрощает анализ и фильтрацию логов.

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