класс 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 «старых» файлов журнала, где каждый файл составляет примерно 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. 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"
})