класс 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 (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. Создайте логгер, который обновляет файл журнала, когда он достигает определенного размера. Оставьте 10 "старых" файлов журнала, где каждый файл составляет около 1 024 000 байт.

   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. Символ или строка (регистр не учитывается)

   logger.level = :info
   logger.level = '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"