Логирование

Данная библиотека позволяет логировать все запросы, включая graphql.

Установка логгера

Для установки логгера необходимо добавить регистр gitlab в конфиг npm, либо использовать .npmrc файл в корне проекта, где будет использоваться библиотека (для установки необходимо заменить gitlab_personal_access_token на Access Token вашего GitLab аккаунта):

Добавление регистра в конфиг:

npm config set @i-link:registry https://gitlab.i-link.pro/api/v4/packages/npm/
npm config set -- '//gitlab.i-link.pro/api/v4/packages/npm/:_authToken' "gitlab_personal_access_token"

Содержание файла .npmrc:

@i-link:registry=https://gitlab.i-link.pro/api/v4/packages/npm/
//gitlab.i-link.pro/api/v4/packages/npm/:_authToken' "gitlab_personal_access_token"

Далее необходимо установить библиотеку:

npm install @i-link/logger

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

import { Module } from '@nestjs/common'
import { LoggerModule } from '@i-link/logger'

@Module({
    imports: [
        LoggerModule.forRootAsync(loggerOptions)
    ]
})
export class SomeModule {
}

Модуль имеет следующие параметры для регистрации, где noColors - это отключение цветного логирования, level - это уровень логирования, который равняется PinoLogLevel типу, а environment - это окружение логирования, используется для разделения логирования на конфигурации:

export type PinoLogLevel =
    | 'trace'
    | 'debug'
    | 'info'
    | 'warn'
    | 'error'
    | 'fatal'
    | 'silent'

export interface ILoggerAsyncOptions {
    environment: string
    noColors?: boolean
    level?: Level
}

Также, для подключения graphql запросов необходимо указать в .env следующий параметр:

LOGGER_GRAPHQL_PREFIX=<ПРЕФИКС_К_ЗАПРОСАМ_ДЛЯ_ВАШЕГО_МИКРОСЕРВИСА>

Общий flow библиотеки

Успешный вызов запроса:

• Сервис принимает запрос и присваивает ему requestId;
• Сервис вызывает метод, декорированный Logging;
• Библиотека получает конфигурации из переменной, при этом конфигурации загружаются из БД;
• Библиотека логирует входящие данные запроса, учитывая параметры конфигурации, и кеширует данные;
• Метод выполняет свою логику и возвращает результат;
• Библиотека логирует исходящие данные запроса;
• Клиент получает ответ от сервера;
• Кешированные данные удаляются.

Вызов запроса с ошибкой:

• Сервис принимает запрос и присваивает ему requestId;
• Сервис вызывает метод, декорированный Logging;
• Библиотека получает конфигурации из переменной, при этом конфигурации загружаются из БД;
• Библиотека логирует входящие данные запроса, учитывая параметры конфигурации, и кеширует данные;
• Метод выполняет свою логику и возвращает ошибку;
• Библиотека логирует все смежные вызовы методов и кеширует данные;
• Библиотека логирует ошибку, учитывая все параметры конфигурации, кеширует данные запроса и отправляет уведомление в систему;
• Клиент получает ответ с ошибкой от сервера;
• Библиотека вытаскивает логи из кеша по requestId, соединяет их и сохраняет в базе данных.

Декоратор класса @Logging

Декоратор класса, выступает, как замена декоратора @TryCatch, так что последний следует удалить.

Декоратор логирует:

• аргументы метода, без имени аргументов
• возвращаемое значение
• ошибки

Следует удалить логи, которые дублируются декоратором. При необходимости сохранения некоторых ручных логов можно не присваивать переменной _logger значение, а лишь определить переменную (по желанию), так как инициализацию с контекстом производит декоратор:

import { Injectable, Logger } from '@nestjs/common'
import { Logging } from '@i-link/logger'

@Logging()
@Injectable()
export class SomeService {
    private readonly _logger: Logger

    async someMethod(): Promise<void> {
        this._logger.debug('Some method was called')
    }
}

Есть возможность добавить методы, которые будут игнорироваться декоратором. За это отвечает свойство ignore.

import { Injectable, Logger } from '@nestjs/common'
import { Logging } from '@i-link/logger'

@Logging({ ignore: ['_privateMethod'] })
@Injectable()
export class SomeService {
    private readonly _logger: Logger

    async someMethod(): Promise<void> {
        this._logger.debug('Some method was called')
    }

    private async _privateMethod(someData: ISomeData): Promise<ISomeModifiedData> {
        // ...logic here
    }
}

Добавление request-id

При подключении модуля LoggerModule автоматически инициализируется middleware для присваивания request-id каждому запросу. Необходимо лишь определить логгер, который будет использовать Nest.JS следующим образом:

import { PinoLoggerService } from './pino-logger.service'

async function bootstrap(): Promise<void> {
    const app = await NestFactory.create(AppModule, {
        logger: true,
    })

    app.useLogger(app.get(PinoLoggerService))

    // ...дальнейшная логика без изменений
}

RMQ контроллеры

1. В конструкторе объявить private readonly _asyncStorageService: AsyncStorageService
2. В аргументы метода подписанного на RMQ сообщения добавить @Uuid() requestId: string
3. В тело метода добавить this._asyncStorageService.requestId = requestId

Cron задачи

1. Добавить импорт import { v4 as uuid } from 'uuid'
2. В конструкторе объявить private readonly _asyncStorageService: AsyncStorageService
3. В тело Cron метода добавить

const requestId = uuid();
this._asyncStorageService.requestId = requestId;

Конфигурация

Конфигурации для классов и методов хранятся в базе данных и подгружаются при запуске сервиса. Это позволяет гибко настраивать логи для разных компонентов приложения.

Таблица log_instances хранит информацию о каждом логируемом классе и методе.

Конфигурация декоратора включает:

• Включение/отключение логирования конкретного класса/метода;
• Логирование данных запросов (входящих/исходящих данных) и их конкретных полей;
• Включение/отключение функции сохранения связных логов при ошибках.

Редактирование конфигураций происходит через API библиотеки. Также, есть возможность статичной первоначальной настройки через параметры декоратора Logging и декоратора DisableLogging.

Для статичного отключения методов используется декоратор @DisableLogging(), а также можно указать отключение логирования методов в параметре ignore декоратора Logging.

Настройка конфигураций

Конфигурации хранят в себе следующие данные:

• name - Название класса/метода для настройки;
• type - Тип конфигурации (класс / метод класса);
• state - Статус конфигурации (активна / отключена), в случае, если конфигурация отключена, то методы логируются целиком;
• logComponent - фильтрация данных логирования, отключает или включает логирование определенных компонентов:
  • request - логировать ли сам запрос, запрос не будет никак отображен в консоли;
  • args - логировать ли аргументы запроса, если отключено, то будет отображено, что был вызван конкретный запрос, но не будут залогированы аргументы запроса;
  • response - логировать ли ответ запроса, ответ не будет никак отображен в консоли;
  • result - логировать ли данные ответа, если отключено, то будет отображено, что метод закончил работу, но данные ответа не будет залогированы;
  • error - логировать ли ошибку.
• formatComponent - фильтрация данных логирование, позволяет отформатировать аргументы/ответ, исключить конкретные поля или выбрать только конкретные поля:
  • args - форматирование аргументов:
    • exclude - массив из ключей аргументов, которые не должны быть залогированы;
    • include - массив из ключей аргументов, которые должны быть залогированы, остальные будут проигнорированы;
  • result - форматирование ответа:
    • exclude - массив из ключей ответа, которые не должны быть залогированы;
    • include - массив из ключей ответа, которые должны быть залогированы, остальные будут проигнорированы;
  • error - форматирование ошибки:
    • exclude - массив из ключей ошибки, которые не должны быть залогированы;
    • include - массив из ключей ошибки, которые должны быть залогированы, остальные будут проигнорированы;
• saveOnError - нужно ли сохранять цепочку запросов при возникновении ошибки.

Общие конфигурации логирования

Библиотека может хранить множество общих конфигураций логирования, которые разделяется на имена. Данные общие конфигурации содержат в себе конфигурации методов и классов, уникальные для каждой общей конфигурации. Как пример, можно разделить библиотеку на несколько конфигураций: debug, info, partial.

• Конфигурация debug будет логировать абсолютно всю информацию, ее конфигурации классов и методов останутся на стандартных настройках;
• Конфигурация info будет логировать только факт вызова и ответа запросов, но ошибки будет логировать полностью и при их возникновении будет сохранять цепочку вызовов, для данной конфигурации нужно будет настроить logComponent поля у классов и методов;
• Конфигурация partial будет логировать только частичные данные, например, только возвращаемые id запросов мутаций;

Различные конфигурации можно переключать в режиме реального времени без необходимости перезапуска микросервиса.

Настройка конфигураций

Настройка конфигураций производится через graphql API, который библиотека автоматически добавляет к основному API сервиса, к которому подключена библиотека. Данные запросы позволяют полностью управлять логированием в режиме реального времени.

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

API для управления конфигурациями:

Запросы для управления общими конфигурациями:

• mutation:createLoggingConfig - создание общей конфигурации, при создании, все конфигурации методов и классов автоматически заполняются для данной общей конфигурации;
• mutation:switchLoggingConfig - переключение конфигурации в реальном времени, автоматически переключит все конфигурации классов и методов;
• query:loggingConfigs - список общих конфигураций.

Запросы для управления конфигурациями классов и методов:

• mutation:updateLoggingInstances - обновление конфигураций методов или классов;
• query:loggingInstances - получение конфигураций методов или классов;

Изменения в конфигурациях при добавлении или изменениях в коде

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

Сохранение цепи вызова при возникновении ошибки

Если на запрос указан параметр saveOnError: true, то в случае возникновения ошибки во время запроса будет сохранена полная цепочка вызова всех методов друг за другом в таблицу log_chains, данная цепочка сохраняет абсолютно все данные целиком и позволяет легко выявить проблему.

Данные из log_chains получаются при помощи GraphQL query запроса loggingChains. Данный запрос вернет все в порядке вызова, также порядок вызова указан в поле order, где порядок указывается по возрастанию, в данной записи указан тип запроса (запрос, ответ или ошибка), а также указывается сама ошибка и данные для каждого запроса.

Производительность

Данная библиотека никоим образом не влияет на скорость выполнения запросов, так как логирование происходит только после завершения запроса. Данные для логирования форматируются и формируются в цепочку в отдельном потоке, который завершается после выполнения запроса в шаге setImmediate.

Миграция со старой версии на новую

Для миграции со старой версии необходимо изменить регистрацию библиотеки, необходимо сменить метод forRoot на forRootAsync, а также дополнительно добавить переменную в .env. При использовании декоратора были вырезаны его параметры, соответственно, нужно удалить все параметры декоратора @Logging(), в случае, если использовался параметр ignore, то необходимо его заменить декоратором DisableLogging(), используемый для конкретного метода.