класс 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. С progname.

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

4. С severity.

   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
   

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"
})