Предназначен для использования в nodejs, с целью сериализации любых сущностей в utf-8 строку и запись в локальный или удаленный лог.
const log = require('/path/to/log.js');
Модуль не ловит глобальные исключения, чтобы сделать это, следует после подключения дописать:
process.on('uncaughtException', log.emerg);
На этапе отладки рекомендуется включить подробный вывод:
log.verbose = true;
- log (any arg, ...)
- Запись лога с меткой
tip
вstderr
. - log.emerg (any arg, ...)
- Запись лога в
stderr
и аварийное завершение процесса. - log.colorize (any arg, ...)
- Ничего не пишет в лог, возвращает аргументы в расцвеченной строке для вывода в терминал.
- log.add (object options)
- возвращает сам себя, при неверном аргументе
options
бросает исключение, добавляет коллекцию потоков логирования (см. "поток логирования"). - log.get (string id)
- возвращает добавленный ранее поток логирования по идентификатору, при отсутствии потока, возвращается поток, который ничего не делает.
log.NONE : 0 log.EMERG : 0 log.ALERT : 1 log.CRIT : 2 log.ERR : 4 log.WARNING : 8 log.NOTICE : 16 log.INFO : 32 log.DEBUG : 64 log.ALL : 127
Предназначены для определения уровня логирования всех потоков числом (см. Таблица 1).
Текущую настройку можно получить или поменять в любой момент.
- log.level
Уровень логирования может быть числом или строкой (см. уровень логирования потока).
Определяет уровень логирования (по умолчанию
log.ALL
) для всех потоков, например:log.level = log.ERR & log.DEBUG;
задает вывод только уровней
ERR
иDEBUG
(иEMERG
, всегда включен). При назначенииlog.level = null;
происходит сброс настроек на определенный при добавлении потока.- log.verbose
- Делает вывод подробным (по умолчанию выключен):
- ошибки пишутся с трэйсом;
- буфера выводятся полностью.
- log.chunked
- Целое число, максимальное количество чанков при передаче логов по протоколу udp. По умолчанию равно 1, т.е. деление на чанки выключено. Максимальное число чанков в graylog равно 128. О способе деления на чанки смотреть здесь.
- log.binary
- Целое число, основание системы счисления при сериализации бинарных данных. Допустимые значения 2, 8, 10, 16. По умолчанию равно 16.
Поток добавляется в модуль, затем его можно получить по идентификатору:
log.add({ id : [ '.tty', '/tmp/log.tab' ] }); const stream = log.get('id');
Аргументом при добавлении потока должен быть словарь, в котором ключом является идентификатор потока, а значением является строка (или массив строк, для случая когда поток записывается не в одно место) определяющая настройку потока. В примере выше, этой настройкой является массив строк. Рекомендуется смотреть "примеры настройки потоков".
Методам потоков допустимо передавать любые аргументы, в любом количестве, для записи в лог:
stream.emerg (any, ...) stream.alert (any, ...) stream.crit (any, ...) stream.err (any, ...) stream.warning (any, ...) stream.notice (any, ...) stream.info (any, ...) stream.debug (any, ...)
Типичные случаи применения смотреть в колонке описание, Таблица 1. Методы ничего не возвращают, исключений не бросают.
Метод `emerg` вызывает аварийное завершение процесса.
Строка настройки потока состоит из частей:
<схема><расположение><формат><уровень>
все части настройки опциональные, но для некоторых комбинаций есть обязательные части. О неверной строке настройки сообщит исключение брошенное при добавлении потока.
По умолчанию, если указан путь, используется схема file:
,
если указан хост и порт, используется udp:
, иначе tty:
.
tty://
- Запись лога в
stdout
. Формат по умолчанию.tty
. file://<path>
- Запись лога в файл, по пути
<path>
. Указание пути обязательно. Формат по умолчанию.tab
. udp://[<family>@]<ip4|ip6|host>:<port>
- Отправка лога по протоколу
udp
на хост, определенный через DNS-запись, или IP-адрес (IPv4 или IPv6, последний должен быть в квадратных скобках[]
). Указание хоста и порта обязательно. При использовании DNS-записи, перед хостом можно указать предпочтительную версию IP,4
или6
, напримерudp://[email protected]:1234
. Формат по умолчанию.syslog
.
Состоит из хоста и/или пути, описано с разделе "Схема потока".
Допустим любой формат для любой схемы потока, определяется как расширение файла
(даже если отсутствует путь файла). Для некоторых форматов могут использоваться
опциональные настройки (они записываются после формата и знака ?
).
По умолчанию, для каждой схемы определен свой формат, его можно переопределить
одним из следующих:
- syslog
Использует для записи стандарт де-факто. Опциональные поля (очень рекомендуется их использовать, это способствует порядку в логах):
?hostname=<string>&appname=<string>&facility=<0-23>
- tab
Формат для записи аргументов в одну строку с разделением табуляцией. Опционально, можно поменять состав и порядок заголовка записи в лог:
?time&name&id
- tty
Формат для печати аргументов в одну строку с разделением табуляцией, расцвеченный для печати в окно терминала (VT100-совместимый). Опционально, можно поменять состав и порядок заголовка записи в лог:
?time&name&id
- io
Формат для записи, с меткой 'ввод/вывод' (в случае печати в терминал, метка цветом), одной переменной (более полезен для буферов и строк), со строковым комментарием и типом переменной, в читаемом виде, основание системы счисления задается настройкой
log.binary
.- В отличие от других форматов,
io
принимает только 3 аргумента: - логический (true/false) ввод/вывод;
- буфер или строка для печати;
- строковый комментарий.
Опционально, можно поменять состав и порядок заголовка записи в лог:
?time&name&id
- В отличие от других форматов,
- gelf
Аргументы преобразуются JSON-запись, согласно спецификации gelf:
{ "version" : "1.1", "host" : <host>, "short_message" : <id>:<level name> <first argument>, "full_message" : <full message>, "timestamp" : <time in ms>, "level" : <level number> }
Опционально, можно (и очень рекомендуется) указать хост:
?<host>
Уровень логирования определяется в настройке фрагментом, в числовом виде или
строкой, например: #1
, или равнозначный #alert
.
Частные случаи:
# #+ #all
- включены все уровни логирования
#-
- все уровни логирования отключены (кроме
EMERG
который всегда включен)
При назначении уровня строкой, допускается неполное имя уровня, например:
#w
, #war
, #warn
, #warning
являются равнозначными, и означают,
что будет записан только лог при использовании метода warning()
.
Чтобы были записаны более критичные методы, необходимо добавить знак +
в
конце, например: #warning+
. Знак +
также служит разделителем
перечисления уровней, например w+c
означает, что будут записаны уровни
warning
и crit
, а запись d+w+c+
означает, что будут записаны уровни
debug
, warning
, crit
и alert
(уровень emerg
пишется всегда).
''
- Пустая строка, запись с расцветкой в
stdout
(при отсутствии хоста и пути, по умолчанию, используется схемаtty
), со всеми заголовками, включены все уровни логирования. '?#-'
- Запись в
stderr
только уровеньemerg
с расцветкой, без заголовков. '#d+w+'
- Запись с расцветкой в
stdout
, со всеми заголовками, включены уровниdebug
,warning
и более критичные. '/tmp/dummy.log'
- Запись в файл
/tmp/dummy.log
, форматtab
(по умолчанию), со всеми заголовками. [ '.io?', '/tmp/dummy.log?time#err+' ]
- Массив строк, запись в два потока:
- в
stdout
с расцветкой, формате ввода/вывода, без заголовков; - файл
/tmp/dummy.log
, форматtab
, с одним заголовком 'время записи', включены уровниerr
и более критичные.
- в
'udp://[email protected]:6514/.gelf?node#notice+'
- Каждая запись лога отправляется
udp
-пакетом (или чанками) на адрес IPv4 который соответствует DNS-записиexample.com
, порт 6514, формат gelf, в который подставляется в полеhost
строкаnode
, включен уровень логированияnotice
и более критичные. '//[::1]/?hostname=node&appname=chat&facility=1'
- Каждая запись лога отправляется
udp
-пакетом (при наличии хоста, по умолчанию, используется схемаudp
) на адрес IPv6::1
(обычно соответствует записи localhost), порт514
(используется по умолчанию), формат syslog; поля:hostname
=node
(имя хоста),appname
=chat
(имя приложения),facility
=1
(сообщения пользовательского уровня); пишутся логи всех уровней. '//6@:6514'
- Каждая запись лога отправляется
udp
-пакетом на адрес IPv6 который соответствует DNS-записиlocalhost
(используется по умолчанию, обычно соответствует[::1]
), порт 6514, формат syslog, пишутся логи всех уровней.
Ротация осуществляется через отправку в родительский процесс nodejs сигнала SIGUSR2 (12). При использовании этого модуля логирования, сигнал SIGUSR2 не приведет к завершению процесса. Пример отправки сигнала:
pkill --signal SIGUSR2 --full 'nodejs /path/to/nodejs-app/'
- При получении сигнала ротации, происходит:
Раз в минуту начиная со старта процесса происходит попытка открытия для не открытых файлов, либо получение IP по DNS-записи, если он ранее не был получен.
Таблица 1. Уровни логирования
Уровень | Метод | Константа | Описание |
---|---|---|---|
NONE | <stream> | Запись только в stderr с пометкой tip |
|
EMERG | emerg | 0 | Отказ системы (дальнейшая работа невозможна) |
ALERT | alert | 1 | Система требует незамедлительного внимания |
CRIT | crit | 2 | Критичное состояние |
ERR | err | 4 | Ошибка |
WARNING | warning | 8 | Предупреждение |
NOTICE | notice | 16 | Значимое информационное сообщение |
INFO | info | 32 | Информационное сообщение |
DEBUG | debug | 64 | Отладочное сообщение |