класс Logger

Описание

Класс Logger предоставляет простой, но мощный инструмент для ведения журнала, который вы можете использовать для вывода сообщений.

Сообщения имеют связанные уровни, такие как INFO или ERROR, которые указывают на их важность. Затем вы можете задать уровень для Logger, и будут отображаться только сообщения с этим уровнем или выше.

Уровни:

UNKNOWN

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

FATAL

Необрабатываемая ошибка, приводящая к аварийному завершению программы.

ERROR

Обрабатываемое условие ошибки.

WARN

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

INFO

Общая (полезная) информация об операциях системы.

DEBUG

Информация низкого уровня для разработчиков.

Например, в производственной системе ваш Logger может быть установлен на INFO или даже на WARN. Однако при разработке системы вам, вероятно, понадобится информация о внутреннем состоянии программы, и вы установите Logger на DEBUG.

Примечание: Logger не экранирует и не очищает любые сообщения, передаваемые ему. Разработчики должны понимать, когда потенциально вредоносные данные (ввод пользователя) передаются в Logger, и вручную экранировать недоверенные данные:

logger.info("User-input: #{input.dump}")
logger.info("User-input: %p" % input)

Вы можете использовать formatter= для экранирования всех данных.

original_formatter = Logger::Formatter.new
logger.formatter = proc { |severity, datetime, progname, msg|
  original_formatter.call(severity, datetime, progname, msg.dump)
}
logger.info(input)

Пример

Это создает Logger, который выводит данные в стандартный поток вывода со уровнем WARN.

require 'logger'

logger = Logger.new(STDOUT)
logger.level = Logger::WARN

logger.debug("Created logger")
logger.info("Program started")
logger.warn("Nothing to do!")

path = "a_non_existent_file"

begin
  File.foreach(path) do |line|
    unless line =~ /^(\w+) = (.*)$/
      logger.error("Line in wrong format: #{line.chomp}")
    end
  end
rescue => err
  logger.fatal("Caught exception; exiting")
  logger.fatal(err)
end

Поскольку уровень Logger установлен на WARN, записываются только предупреждения, ошибки и фатальные сообщения. Сообщения отладки и информационные сообщения отбрасываются.

Особенности

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

Как использовать

Как создать логгер

Ниже приведены различные варианты, от менее до более сложных.

1. Создайте логгер, который записывает сообщения в STDERR/STDOUT.

   logger = Logger.new(STDERR)
   logger = Logger.new(STDOUT)
   

2. Создайте логгер для файла с указанным именем.

   logger = Logger.new('logfile.log')
   

3. Создайте логгер для указанного файла.

   file = File.open('foo.log', File::WRONLY | File::APPEND)
   # To create new logfile, add File::CREAT like:
   # file = File.open('foo.log', File::WRONLY | File::APPEND | File::CREAT)
   logger = Logger.new(file)
   

4. Создайте логгер, который архивирует лог-файл по достижении определенного размера. Оставьте 10 «старых» лог-файлов, где каждый файл составляет около 1024000 байтов.

   logger = Logger.new('foo.log', 10, 1024000)
   

5. Создайте логгер, который архивирует лог-файл ежедневно/еженедельно/ежемесячно.

   logger = Logger.new('foo.log', 'daily')
   logger = Logger.new('foo.log', 'weekly')
   logger = Logger.new('foo.log', 'monthly')
   

Как записать сообщение в журнал

Обратите внимание на различные методы (fatal, error, info), используемые для записи сообщений различных уровней? Другие методы этой группы - warn и debug. add используется ниже для записи сообщения произвольного (возможно, динамического) уровня.

1. Сообщение в блоке.

   logger.fatal { "Argument 'foo' not given." }
   

2. Сообщение как строка.

   logger.error "Argument #{@foo} mismatch."
   

3. С именем программы.

   logger.info('initialize') { "Initializing..." }
   

4. С уровнем тяжести.

   logger.add(Logger::FATAL) { 'Fatal error!' }
   

Форма блока позволяет создавать потенциально сложные сообщения в журнале, но откладывает их оценку до тех пор, пока сообщение не будет записано. Например, если у нас есть следующее:

logger.debug { "This is a " + potentially + " expensive operation" }

Если уровень логгера равен INFO или выше, сообщения отладки не будут записаны в журнал, и весь блок не будет даже оцениваться. Сравните с этим:

logger.debug("This is a " + potentially + " expensive operation")

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

Как закрыть логгер

logger.close

Установка порога уровня тяжести

1. Исходный интерфейс.

   logger.sev_threshold = Logger::WARN
   

2. Интерфейс (частично) совместимый с Log4r.

   logger.level = Logger::INFO
   
   # DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN
   

3. Symbol или String (регистр игнорируется)

   logger.level = :info
   logger.level = 'INFO'
   
   # :debug < :info < :warn < :error < :fatal < :unknown
   

4. Конструктор

   Logger.new(logdev, level: Logger::INFO)
   Logger.new(logdev, level: :info)
   Logger.new(logdev, level: 'INFO')
   

Формат

Сообщения в журнале рендеринг по умолчанию в потоке вывода в определенном формате. Ниже показан формат по умолчанию и пример:

Формат лог-сообщения:

SeverityID, [DateTime #pid] SeverityLabel -- ProgName: message

Пример лог-сообщения:

I, [1999-03-03T02:34:24.895701 #19074]  INFO -- Main: info.

Вы можете изменить формат даты и времени с помощью datetime_format=.

logger.datetime_format = '%Y-%m-%d %H:%M:%S'
      # e.g. "2004-01-03 00:54:26"

или через конструктор.

Logger.new(logdev, datetime_format: '%Y-%m-%d %H:%M:%S')

Или вы можете изменить общий формат с помощью метода formatter=.

logger.formatter = proc do |severity, datetime, progname, msg|
  "#{datetime}: #{msg}\n"
end
# e.g. "2005-09-22 08:51:08 +0900: hello world"

или через конструктор.

Logger.new(logdev, formatter: proc {|severity, datetime, progname, msg|
  "#{datetime}: #{msg}\n"
})