Предназначен для использования в 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

Делает вывод подробным (по умолчанию выключен):

1. ошибки пишутся с трэйсом;
2. буфера выводятся полностью.

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 аргумента:

0. логический (true/false) ввод/вывод;
1. буфер или строка для печати;
2. строковый комментарий.

Опционально, можно поменять состав и порядок заголовка записи в лог:

?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+' ]

Массив строк, запись в два потока:

1. в stdout с расцветкой, формате ввода/вывода, без заголовков;
2. файл /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/'

При получении сигнала ротации, происходит:

1. закрытие (безусловное) и открытие/создание файлов лога;
2. обновление DNS-записи (если хост определен такой записью), при ошибке обновления, логи отправляются на хост с ранее определенным IP-адресом, либо не ведется, если адрес не был получен.

Раз в минуту начиная со старта процесса происходит попытка открытия для не открытых файлов, либо получение IP по DNS-записи, если он ранее не был получен.

Таблица 1. Уровни логирования