класс 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"
})