logging

Этот модуль реализует простой логгер.

Он разработан как можно проще, чтобы избежать избыточности. Если эта библиотека не удовлетворяет вашим потребностям, напишите свою собственную.

Основные возможности

Для начала создайте логгер:

import logging

var logger = newConsoleLogger()

Созданный выше логгер записывает в консоль, но этот модуль также предоставляет логгеры, записывающие в файлы, такие как FileLogger. Также возможно создание пользовательских логгеров, унаследованных от типа Logger.

После создания логгера вызовите его процедуру записи сообщения, чтобы записать сообщение:

logger.log(lvlInfo, "a log message")
# Output: INFO a log message

Значение INFO в выводе является результатом добавления строки форматирования к сообщению, и оно будет отличаться в зависимости от уровня сообщения. Строки форматирования подробно описаны здесь.

Существует шесть уровней ведения журнала: debug, info, notice, warn, error и fatal. Они более подробно описаны в документации перечисления уровня. Сообщение записывается, если его уровень равен или выше уровня логгера levelThreshold и глобального фильтра логов. Последний можно изменить с помощью процедуры setLogFilter.

Предупреждение:

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

Обработчики

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

import logging

var consoleLog = newConsoleLogger()
var fileLog = newFileLogger("errors.log", levelThreshold=lvlError)
var rollingLog = newRollingFileLogger("rolling.log")

addHandler(consoleLog)
addHandler(fileLog)
addHandler(rollingLog)

После этого используйте либо шаблон лога, либо один из шаблонов для определенного уровня, например, шаблон ошибки, чтобы записывать сообщения во все зарегистрированные обработчики сразу.

# This example uses the loggers created above
log(lvlError, "an error occurred")
error("an error occurred")  # Equivalent to the above line
info("something normal happened")  # Will not be written to errors.log

Обратите внимание, что уровень сообщения по-прежнему проверяется для каждого обработчика по отношению к его levelThreshold и глобальному фильтру логов.

Строки форматирования

Сообщения журнала предваряются строками форматирования. Эти строки содержат заполнитель для переменных, таких как $time, которые заменяются соответствующими значениями, такими как текущее время, прежде чем они будут добавлены перед сообщением журнала. Символы, не являющиеся частью переменных, остаются без изменений.

Используемая логгером строка форматирования может быть указана, передав аргумент fmtStr при создании логгера или установив его поле fmtStr позже. Если не указано, используется строка форматирования по умолчанию.

Доступны следующие переменные, которые должны быть префиксрованы символом доллара ($):

Переменная	Вывод
$date	Текущая дата
$time	Текущее время
$datetime	$dateT$time
$app	os.getAppFilename()
$appname	Базовое имя `$app`
$appdir	Имя каталога `$app`
$levelid	Первая буква уровня логирования
$levelname	Имя уровня логирования

Обратите внимание, что $app, $appname, и $appdir не поддерживаются при использовании JavaScript-бекенда.

Следующий пример демонстрирует использование строк форматирования:

import logging

var logger = newConsoleLogger(fmtStr="[$time] - $levelname: ")
logger.log(lvlInfo, "this is a message")
# Output: [19:50:13] - INFO: this is a message

Примечания при использовании нескольких потоков

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

Глобальный фильтр логов на самом деле является потоко-локальной переменной, поэтому его необходимо установить в каждом потоке, использующем этот модуль.
Список зарегистрированных обработчиков также является потоко-локальной переменной. Если обработчик будет использоваться в нескольких потоках, его необходимо зарегистрировать в каждом из этих потоков.

См. также

Модуль strutils для общих функций строк
Модуль strformat для интерполяции строк и форматирования
Модуль strscans для scanf и scanp макросов, которые предлагают более простой способ извлечения подстрок, чем регулярные выражения

Импорты

strutils, times, os

Типы

Level = enum lvlAll, ## All levels active lvlDebug, ## Debug level and above are active lvlInfo, ## Info level and above are active lvlNotice, ## Notice level and above are active lvlWarn, ## Warn level and above are active lvlError, ## Error level and above are active lvlFatal, ## Fatal level and above are active lvlNone ## No levels active; nothing is logged

Перечисление уровней ведения журнала.

Сообщения отладки представляют собой самый низкий уровень ведения журнала, а фатальные сообщения об ошибках – самый высокий. lvlAll можно использовать для включения всех сообщений, а lvlNone можно использовать для их отключения.

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

Debug - отладочная информация, полезная только разработчикам
Info - все, что связано с нормальной работой и не имеет особого значения
Notice - более важная информация, о которой пользователи должны быть проинформированы
Warn - предстоящие проблемы, требующие внимания
Error - ситуации ошибок, из которых приложение может восстановиться
Fatal - фатальные ошибки, которые препятствуют продолжению работы приложения

Приложению полностью предоставлено право на использование каждого уровня.

У отдельных логгеров есть поле levelThreshold , которое фильтрует все сообщения с уровнем ниже порога. Также есть глобальный фильтр, который применяется ко всем сообщениям журнала, и его можно изменить с помощью процедуры setLogFilter.

Исходный код Изменить

Logger = ref object of RootObj levelThreshold*: Level ## Only messages that are at or above this ## threshold will be logged fmtStr*: string ## Format string to prepend to each log message; ## defaultFmtStr is the default

Абстрактный базовый тип всех логгеров.

Пользовательские логгеры должны наследоваться от этого типа. Они также должны предоставить собственную реализацию метода записи.

См. также:

ConsoleLogger
FileLogger
RollingFileLogger

Исходный код Изменить

ConsoleLogger = ref object of Logger useStderr*: bool ## If true, writes to stderr; otherwise, writes to stdout

Логгер, который записывает сообщения журнала в консоль.

Создайте новый ConsoleLogger с помощью процедуры newConsoleLogger.

См. также:

FileLogger
RollingFileLogger

Исходный код Изменить

FileLogger = ref object of Logger file*: File ## The wrapped file

Логгер, который записывает сообщения журнала в файл.

Создайте новый FileLogger с помощью процедуры newFileLogger.

Примечание: Этот логгер недоступен для JavaScript-бекенда.

См. также:

ConsoleLogger
RollingFileLogger

Исходный код Изменить

RollingFileLogger = ref object of FileLogger maxLines: int curLine: int baseName: string baseMode: FileMode logFiles: int bufSize: int

Логгер, который записывает сообщения журнала в файл с ротацией логов.

Создайте новый RollingFileLogger с помощью процедуры newRollingFileLogger.

Примечание: Этот логгер недоступен для JavaScript-бекенда.

См. также:

ConsoleLogger
FileLogger

Исходный код Изменить

Константы

LevelNames: array[Level, string] = ["DEBUG", "DEBUG", "INFO", "NOTICE", "WARN", "ERROR", "FATAL", "NONE"]

Массив строк, представляющих каждый уровень логирования. Исходный код Изменить

defaultFmtStr = "$levelname "

Строка форматирования по умолчанию. Исходный код Изменить

verboseFmtStr = "$levelid, [$datetime] -- $appname: "

Более подробная строка форматирования.

Эту строку можно передать как аргумент frmStr в процедуры, создающие новые логгеры, такие как newConsoleLogger.

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

Исходный код Изменить

Процедуры

proc substituteLog(frmt: string; level: Level; args: varargs[string, `$`]): string {...}{. raises: [], tags: [ReadIOEffect, TimeEffect].}

Форматирует сообщение журнала на указанном уровне с заданной строкой формата.

Переменные формата, присутствующие в frmt, будут заменены соответствующими значениями перед добавлением к args и возвратом.

Если вы не реализуете собственный логгер, вам вряд ли понадобится вызывать эту функцию напрямую. Используйте метод логгера log или один из шаблонов логирования.

См. также:

метод log для ConsoleLogger
метод log для FileLogger
метод log для RollingFileLogger
шаблон логирования

Пример:

doAssert substituteLog(defaultFmtStr, lvlInfo, "a message") == "INFO a message"
doAssert substituteLog("$levelid - ", lvlError, "an error") == "E - an error"
doAssert substituteLog("$levelid", lvlDebug, "error") == "Derror"

logging

Основные возможности

Обработчики

Строки форматирования

Примечания при использовании нескольких потоков

См. также

Импорты

Типы

Константы

Процедуры

Методы

Шаблоны