# Логгер

NocoBase предлагает высокопроизводительную систему логирования, основанную на [pino](https://github.com/pinojs/pino). В любом месте, где доступен `context`, вы можете получить экземпляр логгера через `ctx.logger` для записи ключевых событий во время работы **плагина** или системы.

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

```ts
// Запись критических ошибок (например, сбой инициализации)
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' });
```

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

| Уровень   | Метод              | Описание                                                              |
| --------- | ------------------ | --------------------------------------------------------------------- |
| `fatal`   | `ctx.logger.fatal()` | Критические ошибки, обычно приводящие к завершению работы программы    |
| `error`   | `ctx.logger.error()` | Ошибки, указывающие на сбой запроса или операции                      |
| `warn`    | `ctx.logger.warn()`  | Предупреждения, сигнализирующие о потенциальных рисках или непредвиденных ситуациях |
| `info`    | `ctx.logger.info()`  | Обычная информация о работе                                           |
| `debug`   | `ctx.logger.debug()` | Отладочная информация для среды разработки                            |
| `trace`   | `ctx.logger.trace()` | Подробная информация для трассировки, обычно используемая для глубокой диагностики |

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

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

| Поле       | Тип    | Описание                    |
| ---------- | ------ | --------------------------- |
| `level`    | number | Уровень лога                |
| `time`     | number | Метка времени (миллисекунды) |
| `pid`      | number | ID процесса                 |
| `hostname` | string | Имя хоста                   |
| `msg`      | string | Сообщение лога              |
| `Others`   | object | Пользовательская контекстная информация |

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

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

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

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

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

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

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

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

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

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

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

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

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

| Название уровня | Значение  | Имя метода       | Описание                                                              |
| --------------- | --------- | ---------------- | --------------------------------------------------------------------- |
| `fatal`         | 60        | `logger.fatal()` | Критические ошибки, обычно приводящие к невозможности продолжения работы программы |
| `error`         | 50        | `logger.error()` | Общие ошибки, указывающие на сбой запроса или исключения в работе     |
| `warn`          | 40        | `logger.warn()`  | Предупреждения, сигнализирующие о потенциальных рисках или непредвиденных ситуациях |
| `info`          | 30        | `logger.info()`  | Обычная информация, фиксирующая состояние системы или нормальные операции |
| `debug`         | 20        | `logger.debug()` | Отладочная информация для анализа проблем на этапе разработки         |
| `trace`         | 10        | `logger.trace()` | Подробная информация для трассировки, используемая для глубокой диагностики |
| `silent`        | -Infinity | (нет соответствующего метода) | Отключает весь вывод логов                                            |

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

## Рекомендации по разработке **плагинов**

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

2.  **Различайте уровни логирования**  
    -   Используйте `error` для записи бизнес-исключений.  
    -   Используйте `info` для записи изменений состояния.  
    -   Используйте `debug` для записи отладочной информации в процессе разработки.  

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

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

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