Spec-Zone.ru › Nim

std/logging

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

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

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

Основное использование

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

import std/logging

var logger = newConsoleLogger()

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

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

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

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

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

Предупреждение: Для регистраторов, которые записывают в консоль или в файлы, только сообщения с уровнями error и fatal по умолчанию вызовут немедленное сброс буфера вывода. Установите flushThreshold при создании регистратора, чтобы изменить это.

Обработчики

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

import std/logging

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

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

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

# 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 std/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

Типы

ConsoleLogger = ref object of Logger
  useStderr*: bool           ## If true, writes to stderr; otherwise, writes to stdout
  flushThreshold*: Level     ## Only messages that are at or above this
                             ## threshold will be flushed immediately

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

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

См. также:

  • FileLogger
  • RollingFileLogger
Исходный код Изменить 
FileLogger = ref object of Logger
  file*: File                ## The wrapped file
  flushThreshold*: Level     ## Only messages that are at or above this
                             ## threshold will be flushed immediately

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

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

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

См. также:

  • ConsoleLogger
  • RollingFileLogger
Исходный код Изменить 
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

Перечисление уровней регистрации.

Сообщения debug представляют собой самый низкий уровень регистрации, а сообщения fatal error - самый высокий. 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

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

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

См. также:

  • ConsoleLogger
  • FileLogger
  • RollingFileLogger
Исходный код Изменить 
RollingFileLogger = ref object of FileLogger

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

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

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

См. также:

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

Константы

defaultFmtStr = "$levelname "
Стандартная форматированная строка. Исходный код Изменить 
LevelNames: array[Level, string] = ["DEBUG", "DEBUG", "INFO", "NOTICE", "WARN",
                                    "ERROR", "FATAL", "NONE"]
Массив строк, представляющих каждый уровень регистрации. Исходный код Изменить 
verboseFmtStr = "$levelid, [$datetime] -- $appname: "

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

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

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

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

Процедуры

proc addHandler(handler: Logger) {....raises: [], tags: [], forbids: [].}
Добавляет логгер в список зарегистрированных обработчиков.
Предупреждение: Список обработчиков — это локальная переменная потока. Если данный обработчик будет использоваться в нескольких потоках, эту процедуру следует вызывать в каждом из этих потоков.

См. также:

  • процедуру removeHandler
  • процедуру getHandlers

Пример:

var logger = newConsoleLogger()
addHandler(logger)
doAssert logger in getHandlers()
Исходный код Редактировать 
proc defaultFilename(): string {....raises: [], tags: [ReadIOEffect], forbids: [].}

Возвращает имя файла, используемое по умолчанию при именовании лог-файлов.

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

Исходный код Редактировать 
proc getHandlers(): seq[Logger] {....raises: [], tags: [], forbids: [].}

Возвращает список всех зарегистрированных обработчиков.

См. также:

  • процедуру addHandler
Исходный код Редактировать 
proc getLogFilter(): Level {....raises: [], tags: [], forbids: [].}

Получает глобальный фильтр логов.

См. также:

  • процедуру setLogFilter
Исходный код Редактировать 
proc newConsoleLogger(levelThreshold = lvlAll; fmtStr = defaultFmtStr;
                      useStderr = false; flushThreshold = defaultFlushThreshold): ConsoleLogger {.
    ...raises: [], tags: [], forbids: [].}

Создаёт новый ConsoleLogger.

По умолчанию сообщения логов записываются в stdout. Если useStderr равно true, они записываются в stderr вместо этого.

Для бэкенда JavaScript сообщения логов записываются в консоль, и useStderr игнорируется.

См. также:

  • процедуру newFileLogger, использующую дескриптор файла
  • процедуру newFileLogger, принимающую имя файла
  • процедуру newRollingFileLogger

Примеры:

var normalLog = newConsoleLogger()
var formatLog = newConsoleLogger(fmtStr=verboseFmtStr)
var errorLog = newConsoleLogger(levelThreshold=lvlError, useStderr=true)
Исходный код Редактировать 
proc newFileLogger(file: File; levelThreshold = lvlAll; fmtStr = defaultFmtStr;
                   flushThreshold = defaultFlushThreshold): FileLogger {.
    ...raises: [], tags: [], forbids: [].}

Создаёт новый FileLogger, использующий предоставленный дескриптор файла.

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

См. также:

  • процедуру newConsoleLogger
  • процедуру newFileLogger, принимающую имя файла
  • процедуру newRollingFileLogger

Примеры:

var messages = open("messages.log", fmWrite)
var formatted = open("formatted.log", fmWrite)
var errors = open("errors.log", fmWrite)

var normalLog = newFileLogger(messages)
var formatLog = newFileLogger(formatted, fmtStr=verboseFmtStr)
var errorLog = newFileLogger(errors, levelThreshold=lvlError)
Исходный код Редактировать 
proc newFileLogger(filename = defaultFilename(); mode: FileMode = fmAppend;
                   levelThreshold = lvlAll; fmtStr = defaultFmtStr;
                   bufSize: int = -1; flushThreshold = defaultFlushThreshold): FileLogger {.
    ...raises: [IOError], tags: [], forbids: [].}

Создаёт новый FileLogger, записывающий в файл с указанным именем.

bufSize управляет размером буфера вывода, используемого при записи в лог-файл. Доступны следующие значения:

  • -1 — использовать системные значения по умолчанию
  • 0 — не буферизовать
  • > 0 — фиксированный размер буфера

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

См. также:

  • процедуру newConsoleLogger
  • процедуру newFileLogger, использующую дескриптор файла
  • процедуру newRollingFileLogger

Примеры:

var normalLog = newFileLogger("messages.log")
var formatLog = newFileLogger("formatted.log", fmtStr=verboseFmtStr)
var errorLog = newFileLogger("errors.log", levelThreshold=lvlError)
Исходный код Редактировать 
proc newRollingFileLogger(filename = defaultFilename();
                          mode: FileMode = fmReadWrite; levelThreshold = lvlAll;
                          fmtStr = defaultFmtStr; maxLines: Positive = 1000;
                          bufSize: int = -1;
                          flushThreshold = defaultFlushThreshold): RollingFileLogger {.
    ...raises: [IOError, OSError], tags: [ReadDirEffect, ReadIOEffect], forbids: [].}

Создаёт новый RollingFileLogger.

После того, как текущий лог-файл, в который происходит запись, содержит maxLines строк, будет создан новый лог-файл, а старый лог-файл будет переименован.

bufSize управляет размером буфера вывода, используемого при записи в лог-файл. Доступны следующие значения:

  • -1 — использовать системные значения по умолчанию
  • 0 — не буферизовать
  • > 0 — фиксированный размер буфера

Примечание: Эта процедура недоступна в бэкенде JavaScript.

См. также:

  • процедуру newConsoleLogger
  • процедуру newFileLogger, использующую дескриптор файла
  • процедуру newFileLogger, принимающую имя файла

Примеры:

var normalLog = newRollingFileLogger("messages.log")
var formatLog = newRollingFileLogger("formatted.log", fmtStr=verboseFmtStr)
var shortLog = newRollingFileLogger("short.log", maxLines=200)
var errorLog = newRollingFileLogger("errors.log", levelThreshold=lvlError)
Исходный код Редактировать 
proc removeHandler(handler: Logger) {....raises: [], tags: [], forbids: [].}

Удаляет логгер из списка зарегистрированных обработчиков.

Обратите внимание, что при n-кратном регистрации логгера требуется n вызовов этой процедуры для его удаления.

Исходный код Редактировать 
proc setLogFilter(lvl: Level) {....raises: [], tags: [], forbids: [].}

Устанавливает глобальный фильтр логов.

Сообщения ниже указанного уровня не будут регистрироваться независимо от levelThreshold отдельного логгера. По умолчанию все сообщения регистрируются.

Предупреждение: Глобальный фильтр логов — это локальная переменная потока. Если выполняется регистрация логов в нескольких потоках, эта процедура должна вызываться в каждом потоке, если не предполагается, что разные потоки должны регистрировать логи на разных уровнях.

См. также:

  • процедуру getLogFilter

Пример:

setLogFilter(lvlError)
doAssert getLogFilter() == lvlError
Исходный код Редактировать 
proc substituteLog(frmt: string; level: Level; args: varargs[string, `$`]): string {.
    ...raises: [], tags: [ReadIOEffect, TimeEffect], forbids: [].}

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

Переменные формата формата, присутствующие в 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"
Исходный код Редактировать

Методы

method log(logger: ConsoleLogger; level: Level; args: varargs[string, `$`]) {.
    ...raises: [], tags: [ReadIOEffect, TimeEffect, WriteIOEffect], forbids: [].}

Записывает в консоль с использованием только данного ConsoleLogger.

Этот метод игнорирует список зарегистрированных обработчиков.

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

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

См. также:

  • метод log для FileLogger
  • метод log для RollingFileLogger
  • шаблон лога

Примеры:

var consoleLog = newConsoleLogger()
consoleLog.log(lvlInfo, "this is a message")
consoleLog.log(lvlError, "error code is: ", 404)
Исходный код Редактировать 
method log(logger: FileLogger; level: Level; args: varargs[string, `$`]) {.
    ...raises: [IOError], tags: [WriteIOEffect, ReadIOEffect, TimeEffect],
    forbids: [].}

Записывает сообщение на указанном уровне с использованием только данного FileLogger.

Этот метод игнорирует список зарегистрированных обработчиков.

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

Примечания:

  • По умолчанию только сообщения об ошибках и критические ошибки заставляют буфер вывода немедленно сбросить. Установите flushThreshold при создании логгера, чтобы изменить это.
  • Этот метод недоступен для JavaScript-бэкенда.

См. также:

  • метод log для ConsoleLogger
  • метод log для RollingFileLogger
  • шаблон лога

Примеры:

var fileLog = newFileLogger("messages.log")
fileLog.log(lvlInfo, "this is a message")
fileLog.log(lvlError, "error code is: ", 404)
Исходный код Редактировать 
method log(logger: Logger; level: Level; args: varargs[string, `$`]) {.
    ...raises: [Exception], gcsafe, tags: [RootEffect], base, ...forbids: [].}

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

См. также:

  • метод log для ConsoleLogger
  • метод log для FileLogger
  • метод log для RollingFileLogger
  • шаблон лога
Исходный код Редактировать 
method log(logger: RollingFileLogger; level: Level; args: varargs[string, `$`]) {.
    ...raises: [OSError, IOError],
    tags: [ReadDirEffect, ReadIOEffect, WriteIOEffect, TimeEffect], forbids: [].}

Записывает сообщение на указанном уровне с использованием только данного RollingFileLogger.

Этот метод игнорирует список зарегистрированных обработчиков.

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

Примечания:

  • По умолчанию только сообщения об ошибках и критические ошибки заставляют буфер вывода немедленно сбросить. Установите flushThreshold при создании логгера, чтобы изменить это.
  • Этот метод недоступен для JavaScript-бэкенда.

См. также:

  • метод log для ConsoleLogger
  • метод log для FileLogger
  • шаблон лога

Примеры:

var rollingLog = newRollingFileLogger("messages.log")
rollingLog.log(lvlInfo, "this is a message")
rollingLog.log(lvlError, "error code is: ", 404)
Исходный код Редактировать

Шаблоны

template debug(args: varargs[string, `$`])

Записывает отладочное сообщение во все зарегистрированные обработчики.

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

Примеры:

var logger = newConsoleLogger()
addHandler(logger)

debug("myProc called with arguments: foo, 5")

См. также:

  • шаблон лога
  • шаблон info
  • шаблон notice
Исходный код Редактировать 
template error(args: varargs[string, `$`])

Записывает сообщение об ошибке во все зарегистрированные обработчики.

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

Примеры:

var logger = newConsoleLogger()
addHandler(logger)

error("An exception occurred while processing the form.")

См. также:

  • шаблон лога
  • шаблон предупреждения
  • шаблон критической ошибки
Исходный код Редактировать 
template fatal(args: varargs[string, `$`])

Записывает сообщение о критической ошибке во все зарегистрированные обработчики.

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

Примеры:

var logger = newConsoleLogger()
addHandler(logger)

fatal("Can't open database -- exiting.")

См. также:

  • шаблон лога
  • шаблон предупреждения
  • шаблон ошибки
Исходный код Редактировать 
template info(args: varargs[string, `$`])

Записывает информационное сообщение во все зарегистрированные обработчики.

Информационные сообщения обычно генерируются во время нормальной работы приложения и не имеют особого значения. Может быть полезно агрегировать эти сообщения для последующего анализа.

Примеры:

var logger = newConsoleLogger()
addHandler(logger)

info("Application started successfully.")

См. также:

  • шаблон лога
  • шаблон отладки
  • шаблон notice
Исходный код Редактировать 
template log(level: Level; args: varargs[string, `$`])

Записывает сообщение на указанном уровне во все зарегистрированные обработчики.

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

Примеры:

var logger = newConsoleLogger()
addHandler(logger)

log(lvlInfo, "This is an example.")

См. также:

  • шаблон отладки
  • шаблон info
  • шаблон notice
  • шаблон предупреждения
  • шаблон ошибки
  • шаблон критической ошибки
Исходный код Редактировать 
template notice(args: varargs[string, `$`])

Записывает сообщение notice во все зарегистрированные обработчики.

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

Примеры:

var logger = newConsoleLogger()
addHandler(logger)

notice("An important operation has completed.")

См. также:

  • шаблон лога
  • шаблон отладки
  • шаблон info
Исходный код Редактировать 
template warn(args: varargs[string, `$`])

Записывает предупреждение во все зарегистрированные обработчики.

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

Примеры:

var logger = newConsoleLogger()
addHandler(logger)

warn("The previous operation took too long to process.")

См. также:

  • шаблон лога
  • шаблон ошибки
  • шаблон критической ошибки
Исходный код Редактировать

© 2006–2024 Andreas Rumpf
Licensed under the MIT License.
https://nim-lang.org/docs/logging.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API