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

Руководства

Как создать Logger

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

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

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

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

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

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

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

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

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

5. Создайте Logger, который переключает файл журнала ежедневно/еженедельно/ежемесячно.

   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. С progname.

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

4. С severity.

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

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

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

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

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

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

Как закрыть Logger

logger.close

Установка порога серьезности

1. Оригинальный интерфейс.

   logger.sev_threshold = Logger::WARN
   

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

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

Формат

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

Формат журнала:

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"

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

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