@skbkontur/logger

Client for sendings logs in kontur elk

Usage no npm install needed!

<script type="module">
  import skbkonturLogger from 'https://cdn.skypack.dev/@skbkontur/logger';
</script>

README

Node.logger - стандартный логгер для node.js проектов

Мы используем стандартные для контура уровни логирования:

const levels = {
  fatal: 0,
  error: 1,
  warn: 2,
  info: 3,
  debug: 4,
  trace: 5
};

Как пользоваться логером

import Logger from '@skbkontur/logger';
import os from 'os';

const logger = Logger.create({
  identity: `my-app.${os.hostname()}`,
  loggerIndexPrefix: 'project-cloud-my.app',
  loggerApiKey: '<secret>',
  allowedMetaFields: ['metakey']
});

logger.info('hello all', { metakey: 1 });

ILoggerConfig

Обязательные свойства

loggerIndexPrefix - префикс логов в ELK.
loggerApiKey - апи ключ к ELK.

Опциональные свойства

loggerServerName - адрес ELK, куда будет отправлять логи KonturELKTransport. По умолчанию: 'https://elk-relay.skbkontur.ru'.

identity - идентификатор приложения. К каждому сообщению будет приложено поле identity по которому можно будет фильтров. По умолчанию: 'default'.

maximumLevel - Максимальный уровень логирования. По умолчанию: 'info' (не логируются 'trace' и 'debug').

allowedMetaFields - список полей которые не будут отброшены при отправке лога. Например если вы хотите отправлять:

logger.info('Chto to sluchilos', { a: 1, b: 2 });

allowedMetaFields: ['a', 'b']. По умолчанию: [].

Задать уровень по умолчанию для метода logger.log

Создайте логгер с использованием функции Logger.createWithDefaultLevel. Вторым параметром передайте уровень с которым будут логироваться сообщения в logger.log.

import Logger from '@skbkontur/logger';
import os from 'os';

const logger = Logger.createWithDefaultLevel(
  {
    identity: `my-app.${os.hostname()}`,
    loggerIndexPrefix: 'project-cloud-my.app',
    loggerApiKey: '<secret>',
    allowedMetaFields: ['metakey']
  },
  'debug'
);

logger.log({ metakey: 1 });

Как использовать winston-transport

В контуре нестандартный ELK гейт, поэтому стандартный ELK транспорт для отправки логов не работает.

Если вы хотите самостоятельно создать инстанс winston логера, вы можете воспользоваться транспортом из этого пакета.

import { KonturELKTransport } from '@skbkontur/logger';

Получить инстанс winston с дефолтными для контура настройками

import createLogger from '@skbkontur/logger/lib/createLogger';

const winston = createLogger({
  identity: `my-app.${os.hostname()}`,
  loggerIndexPrefix: 'project-cloud-my.app',
  loggerApiKey: '<secret>',
  allowedMetaFields: ['metakey']
});

В качестве конфига передается все тот же ILoggerConfig.

Самостоятельно доконфигурировать инстанс winston

Уже имеющийся инстанс winston можно доконфигурировать с использованием методов .clear, .add, .remove, .configure. Пользуйтесь документацией winston@3.

При использовании Logger

logger.winstonInstance.configure({ ...newWinstonLoggerOptions });