Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

@tinkoff/logger

Package Overview
Dependencies
Maintainers
15
Versions
57
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@tinkoff/logger - npm Package Compare versions

Comparing version 0.10.7 to 0.10.8

2

package.json
{
"name": "@tinkoff/logger",
"version": "0.10.7",
"version": "0.10.8",
"description": "",

@@ -5,0 +5,0 @@ "main": "lib/index.js",

316

README.md
# Logger
Библиотека логгирования
Logging library
## Подключение
## Installation
Устанавливаем npm модуль
Install using package manager, e.g. for npm:

@@ -13,3 +13,3 @@ ```bash

или
for yarn:

@@ -20,86 +20,12 @@ ```bash

## Использование библиотеки
## Api
```javascript
import logger from '@tinkoff/logger'; // импорт логгера
### Child loggers
const log = logger('my-component'); // создаем новый логер с идентификатором my-component. Этот индетификатор будет добавлен к каждому логу в поле name. Стоит задавать уникальные индетификаторы, так как можно будет проще найти логи
You can create child loggers using method `.child` of the current logger instance. Child logger will inherit parent logger settings and can override these settings.
// мы можем логировать данные с разным уровнем, чем ниже уровень, тем критичней лог.
log.trace('trace');
log.debug('debug');
log.info({ event: 'client-visited', message: 'client visited tinkoff.ru' });
log.warn('warn');
log.error({ event: 'form-send-error', error: new Error('form') });
log.fatal('fatal error');
```
Про уровни логгирования и что они обозначают можно почитать [статью](https://www.scalyr.com/blog/logging-levels/).
## Как правильно логгировать
Для правильного логгирования на клиенте и на сервере, предпочтительно использовать следующий формат:
```tsx
interface Log {
event?: string; // уникальный индетификатор события, который можно будет просто найти в системе учетов логов
message?: string; // описание лога
error?: Error; // ошибка, если она есть
[key]: any; // любые другие данные
}
```
- Если надо просто залогировать некий текст, то склеиваем все сообщение в один аргумент и просто передаем в логгер. В json формате этот текст будет доступен в поле `message`
```tsx
logger.info('hello logger'); // идентично logger.info({ message: 'hello logger' });
```
- Если необходимо залогировать некий объект или много аргументов, то собираем все в один объект и передаем в логер
```tsx
logger.warn({
message: 'be warn',
event: 'my-warning', // event - стандартный ключ для обозначения конкретного события
...obj1,
...obj2,
a: 1,
b: 2,
});
```
- Если необходимо залогировать объект ошибки, то либо передаем саму ошибку под ключом `error`, либо явно передаем в логгер первым аргументом
```tsx
logger.error({
error: new Error('message'),
});
logger.error(new Error('message'));
logger.error(new Error('typeError'), 'custom error message'); // специальный формат для переопределения текста ошибки
```
- Если в логгер было переданно несколько аргументов, то первый аргумент будет обработается по правилам выше, а остальные аргументы отдельно добавятся в поле args результат
```tsx
logger.debug(
{
event: 'watch',
data: 'some data',
},
'arg2',
'arg3'
);
```
Данный формат прежде всего нужен для удобной работы с логами во внешних системах вроде kibana, splunk. Поэтому желательно его придерживаться, иначе возможны сложности с поиском и анализом логов.
## Дочерние логгеры
С помощью метода инстанса логгера `.child` можно создавать дочерние логгеры для данного инстанса, которые будут наследовать конфигурацию родительского логгера и могут эту конфигурацию переопределять.
```tsx
const log = logger({ name: 'test' });
const childLog = log.child('child'); // т.к. логгер дочерний то его итоговое имя будет 'test.child'
const childLog = log.child('child'); // as this logger is child logger the result name will be 'test.child'

@@ -109,3 +35,3 @@ const childLogWithDefaults = log.child({

defaults: {
// defaults позволяет задать объект все свойства которого будут вмержены в объекты логов залогированных данным логгером
// defaults might be used to specify properties which will be merged to log objects logged with this logger
child: true,

@@ -117,3 +43,3 @@ },

name: 'override',
reporters: [], // позволяет переопределить настройки родительского логгера
reporters: [], // may override settings of the parent logger
filters: [],

@@ -124,28 +50,28 @@ extensions: [],

## Отображение логов
### Display logs
Библиотека дает возможность установить уровень логгирования, отображать или скрывать логи различных экземпляров логгера, и очищать все настройки.
Library allows to specify used logging level, show/hide logs for specific instances of the logger, reset display settings.
По умолчанию, уровень логгирования выставлен как `error` для всех логгеров.
By default, `error` level is used for every logger.
Добавление отображения уникального логгера с уровнем выше `error`, например `logger.enable('info', 'my-logger')`, переопределяет уровень логгирования только для `my-logger`.
Settings display level higher than `error` for single logger, e.g. `logger.enable('info', 'my-logger')`, overrides logging level only for `my-logger`.
Нельзя сделать уровень логгирования для определенного логгера ниже, чем общий уровень, например при установленном по умолчанию уровне `error` запись `logger.enable('fatal', 'my-logger')` ничего не изменит в отображаемых логах.
It is impossible to set logging level lower than common level, e.g. when using common logging level equal to `error` calls to `logger.enable('fatal', 'my-logger')` changes nothing.
Каждое добавление уникальных настроек отображения для нового логгера не влияет на предыдущие, например отдельные вызовы методов `logger.enable('info', 'my-logger')` и `logger.enable('trace', 'yet-another-logger')` будут работать независимо друг от друга.
All subsequent setup for log displaying are preserved, e.g. subsequent calls `logger.enable('info', 'my-logger')` and `logger.enable('trace', 'yet-another-logger')` will enable logs to both logger according to their settings.
### Отображение логов на сервере
#### Display logs on server
Для настройки отображения логов на сервере используются переменные окружения `LOG_LEVEL` и `LOG_ENABLE` (параметры можно задавать вместе, тогда сначала проверяется _LOG_LEVEL_ настройка, потом _LOG_ENABLE_):
For control of displaying logs on server environment variables `LOG_LEVEL` and `LOG_ENABLE` are used:
- LOG_LEVEL = trace | debug | info | warn | error | fatal - включает отображение логов для заданного уровня и все уровней выше. Пример:
- если `LOG_LEVEL=info`, то будут отображаться все логи уровней info, warn, error, fatal
- LOG_ENABLE = `${name}` | `${level}:${name}` - позволяет включить отображение всех логов по определенному имени логгера или по определенному имени и уровню. Несколько вхождений передаются через запятую. Примеры:
- если `LOG_ENABLE=server`, то будут отображены логи всех уровней с именем `server`
- если `LOG_ENABLE=trace:server*`, то будут отображены только логи для `server` с уровнем `trace`
- если `LOG_ENABLE=info:server,client,trace:shared`, то будут включены логи для заданных логгеров по правилам выше
- LOG_LEVEL = trace | debug | info | warn | error | fatal - enables displaying logs for specified level and higher. E.g.:
- if `LOG_LEVEL=info` then all logs of levels info, warn, error, fatal will be showed.
- LOG_ENABLE = `${name}` | `${level}:${name}` - let to enable displaying logs for a specific name and level. It can accept several entries that are passed as comma-separated. E.g.:
- if `LOG_ENABLE=server` then all logs for name `server` will be displayed
- if `LOG_ENABLE=trace:server*` then for logs with name server only `trace` level will be showed
- if `LOG_ENABLE=info:server,client,trace:shared` then displaying logs will be enabled for specified loggers using rules above
### Отображение логов в браузере
#### Display logs in browser
В браузере настройки сохраняются в localStorage, поэтому для отображения всех клиентских логов с новыми настройками, надо дополнительно перезагрузить страницу, либо очистить localStorage. Для удобной настройки параметров отображения в `window` добавляется объект `logger` через который можно настраивать отображение логов в браузере.
In browser display settings are stored in localStorage, so it will work even after page reloads. In order to reset settings you may clear localStorage. For convenient usage a special object `logger` is added to window object in the browser.

@@ -155,18 +81,18 @@ ```tsx

logger.setLevel('warn'); // отображать логи уровня warn и выше
logger.setLevel('warn'); // enable displaying log for level `warn` and higher
logger.enable('info', 'test'); // также отображать вывод логгера test уровня info
logger.enable('info', 'test'); // enable displaying logs for logger `test` with level `info` также отображать вывод логгера test уровня info
logger.enable('my-logger'); // включить полное отображение логгера my-logger
logger.enable('my-logger'); // show all logs for logger `my-logger`
logger.enable('perf*'); // включить все логи имя которых начинается с perf
logger.enable('perf*'); // enable all logs with name starting with `perf`
logger.disable('my-logger'); // отключить логгирование для заданного пространства имен
logger.disable('my-logger'); // disable displaying logs for `my-logger`
logger.clear(); // очистить все настройки (отключение отображения логов)
logger.clear(); // reset all settings
```
## Конфигурация
### Configuration
#### Конфигурация локального логгера
#### Local logger configuration

@@ -176,4 +102,4 @@ ```javascript

const log = logger({ name: 'my-logger' }); // задание name обязательно для идентификации логгера
const log = logger('my-logger'); // краткая запись, аналогичная предыдущей строке
const log = logger({ name: 'my-logger' }); // name is required field in order to identify logs
const log = logger('my-logger'); // same as above

@@ -188,13 +114,13 @@ const log = logger({

Параметры:
Options:
- `name[='log']` - имя нового логгера
- `name[='log']` - name of the new logger
## Расширение возможностей логгера
### Extend logger functionality
`@tinkoff/logger` можно расширять различными действиями:
`@tinkoff/logger` might be extended using next entities:
### Фильтры
#### Filter
Фильтры позволяют отключать логгирование орпеделенных логов в зависимости от условий
Filters can disable logging for specific logs base on inner conditions

@@ -208,9 +134,9 @@ ```tsx

logger.addFilter(filter as Filter); // добавить фильтр вдобавок к заданными по умолчанию и добавленным ранее
logger.setFilters([filter1, filter2]); // заменить текущие фильтры на переданные (что также позволит переделать поведение по умолчанию)
logger.addFilter(filter as Filter); // add new filter to list of previously added filters
logger.setFilters([filter1, filter2]); // replace current filters with passed list. that allows to override default settings
```
### Расширения данных
#### Extension
Расширения позволяют расширять или переопределять объект лога перед его логгированием
Extensions can extend or override log object before making actual logging

@@ -224,13 +150,13 @@ ```tsx

logger.addExtension(extension as Extension); // добавить расширение вдобавок к заданными по умолчанию и добавленным ранее
logger.setExtensions([extension1, extension2]); // заменить текущие расшиерния на переданные (что также позволит переделать поведение по умолчанию)
logger.addExtension(extension as Extension); // add new extension to list of previously added extensions
logger.setExtensions([extension1, extension2]); // replace current extensions with passed list. that allows to override default settings
```
### Репортеры
#### Reporter
Репортеры позволяют настраивать вид отображения логов (json, красочные логи для браузера, отправка логов на апи).
Reporters can change the way logs are showed (json, fancy logs in browser, send logs to remote api).
По умолчанию подключены репортеры для отображения логов в консоли на основании [настроек отображения ](#просмотр-логов).
Be default, enabled only reporters for displaying logs in console based on [display logs settings](#display-logs)
Такие репортеры зависят от настроек уровня и включенных логгеров, т.е. такие репортеры не вызываются если уровень текущего лога ниже настроек или для данного имени логи не включены.
Reporters are depends of logger level settings as reporters will not be called if level of the current log are lower than display logs setting

@@ -244,9 +170,9 @@ ```tsx

logger.addReporter(reporter as Reporter); // добавить репортер вдобавок к заданными по умолчанию и добавленным ранее
logger.setReporters([reporter1, reporter2]); // заменить текущие репортеры на переданные (что также позволит переделать поведение по умолчанию)
logger.addReporter(reporter as Reporter); // add new reporter to list of previously added reporters
logger.setReporters([reporter1, reporter2]); // replace current reporters with passed list. that allows to override default settings
```
### Безусловные репортеры
#### BeforeReporter
Тоже самое что и обычные репортеры, но вызываются безусловно для всех логов и до всей остальной логики с фильтрами и расширениями.
Same as usual `Reporter` but `BeforeReporter` are called unconditionally for every log and get called before any other extension.

@@ -260,29 +186,29 @@ ```tsx

logger.addBeforeReporter(reporter as Reporter); // добавить репортер вдобавок к заданными по умолчанию и добавленным ранее
logger.setBeforeReporters([reporter1, reporter2]); // заменить текущие репортеры на переданные (что также позволит переделать поведение по умолчанию)
logger.addBeforeReporter(reporter as Reporter); // add new beforeReporter to list of previously added beforeReporter
logger.setBeforeReporters([reporter1, reporter2]); // replace current beforeReporters with passed list. that allows to override default settings
```
## Готовые репортеры
### Bundled Reporters
### BrowserReporter
#### BrowserReporter
Стандартный логгер для отображения логов в браузере.
Standard reporter to show logs in browser
### NodeDevReporter
#### NodeDevReporter
Стандартный логгер для отображения логов в консоли на сервере, цветной и с удобным форматированием.
Standard reporter to showing logs in the server console with handy formatting
Используется по умолчанию в дев режиме или если задана `process.env.DEBUG_PLAIN`.
Used by default in dev-mode or if environment variable `process.env.DEBUG_PLAIN` is specified.
### NodeBasicReporter
#### NodeBasicReporter
Репортер для отображения логов в консоли на сервере, минималистичный.
Minimal reporter to showing logs in the server console.
### JSONReporter
#### JSONReporter
Отображение логов в виде json.
Show logs in json format.
### RemoteReporter
#### RemoteReporter
Репортер для отправки логов на апи.
Sends logs on remote api.

@@ -293,6 +219,6 @@ ```tsx

const remote = new RemoteReporter({
requestCount: 1, // кол-во запросов которые могут быть отправлено параллельно
emitLevels: { error: true, fatal: true }, // уровни которые будут по умолчанию логгироваться на апи
requestCount: 1, // number of parallel request
emitLevels: { error: true, fatal: true }, // log levels which will be send to api
async makeRequest(logObj) {
// функция которая принимает текущий лог и отправляет запрос на апи
// function that accepts log object and sends data to api
return await request();

@@ -304,16 +230,94 @@ },

const log = logger({ name: 'test-remote' }); // настройки для remote будут использованы из настроек RemoteReporter
const log = logger({ name: 'test-remote' }); // settings for remote will be inherited from RemoteReporter itself
log.error('error'); // лог также отправится на апи
log.info('test'); // не отправится на апи т.к. уровень не error и не fatal
log.error('error'); // will be sent to api
log.info('test'); // will not be sent to api
const remoteLog = logger({ name: 'remote-for-all', remote: true }); // remote перебивает настройки RemoteReporter и отправляет логи в любом случае
const remoteLog = logger({ name: 'remote-for-all', remote: true }); // `remote` allows to override settings from RemoteReporter and send logs unconditionally
remoteLog.info('test'); // отправится на апи
remoteLog.debug('test'); // отправится
remoteLog.info('test'); // will be sent to api
remoteLog.debug('test'); // will be sent to api
const traceLog = logger({ name: 'log-trace', emitLevels: { trace: true } }); // переписать настройки RemoteReporter
const traceLog = logger({ name: 'log-trace', emitLevels: { trace: true } }); // override RemoteReporter settings
traceLog.trace('test'); // отправится на апи
traceLog.error('test'); // не отправится
traceLog.trace('test'); // will be sent to api
traceLog.error('test'); // will not be sent to api
```
## How to
### Base usage
```javascript
import logger from '@tinkoff/logger'; // import logger
const log = logger('my-component'); // create new logger with an id `my-component`. This id will be added for every log at field `name`. Using unique ids will help to find source of the logs
// logs can be created with different levels
log.trace('trace');
log.debug('debug');
log.info({ event: 'client-visited', message: 'client visited tinkoff.ru' });
log.warn('warn');
log.error({ event: 'form-send-error', error: new Error('form') });
log.fatal('fatal error');
```
More about logging level and what do they mean in [the article](https://www.scalyr.com/blog/logging-levels/).
## How to log properly
To log properly it is suitable to use next format:
```tsx
interface Log {
event?: string; // unique id of event which is might be easily found in log management tool
message?: string; // log description
error?: Error; // error if appropriate
[key]: any; // any other data
}
```
- In case of logging simple text just use string template to pass result string to logger. For json format this string will be available in the `message` props.
```tsx
logger.info('hello logger'); // identical to logger.info({ message: 'hello logger' });
```
- In order to log some object or many arguments, compile they together to single object:
```tsx
logger.warn({
message: 'be warn',
event: 'my-warning',
...obj1,
...obj2,
a: 1,
b: 2,
});
```
- In order to log error object either pass the error with the props `error` or pass it to logger as only argument
```tsx
logger.error({
error: new Error('message'),
});
logger.error(new Error('message'));
logger.error(new Error('typeError'), 'custom error message'); // a special format to redefine error message
```
- In case of several arguments were passed to logger then only the first argument will be proceeded with the rules from above while all of the other arguments will be passed as an `args` props
```tsx
logger.debug(
{
event: 'watch',
data: 'some data',
},
'arg2',
'arg3'
);
```
These formatting rules are handful to connect logging to external tools like kibana, splunk. So it is desirable to follow these rules, otherwise it may lead to troubles with searching and analyzing your logs.
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc