класс 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 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. С именем программы.

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

4. С уровнем важности.

   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
   

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

не используется после 1.2.7. только для совместимости.