класс Logger

Класс Logger предоставляет простую, но сложную утилиту для ведения журналов, которую вы можете использовать для создания одного или нескольких журналов событий для вашей программы. Каждый такой журнал содержит хронологическую последовательность записей, которая обеспечивает запись деятельности программы.

О примерах

Все примеры на этой странице предполагают, что Logger был подключается:

require 'logger'

Синопсис

Создайте журнал с помощью Logger.new:

# Single log file.
logger = Logger.new('t.log')
# Size-based rotated logging: 3 10-megabyte files.
logger = Logger.new('t.log', 3, 10485760)
# Period-based rotated logging: daily (also allowed: 'weekly', 'monthly').
logger = Logger.new('t.log', 'daily')
# Log to an IO stream.
logger = Logger.new($stdout)

Добавьте записи (уровень, сообщение) с помощью Logger#add:

logger.add(Logger::DEBUG, 'Maximal debugging info')
logger.add(Logger::INFO, 'Non-error information')
logger.add(Logger::WARN, 'Non-error warning')
logger.add(Logger::ERROR, 'Non-fatal error')
logger.add(Logger::FATAL, 'Fatal error')
logger.add(Logger::UNKNOWN, 'Most severe')

Закройте журнал с помощью Logger#close:

logger.close

Записи

Вы можете добавить записи с помощью метода Logger#add:

logger.add(Logger::DEBUG, 'Maximal debugging info')
logger.add(Logger::INFO, 'Non-error information')
logger.add(Logger::WARN, 'Non-error warning')
logger.add(Logger::ERROR, 'Non-fatal error')
logger.add(Logger::FATAL, 'Fatal error')
logger.add(Logger::UNKNOWN, 'Most severe')

Эти сокращённые методы также добавляют записи:

logger.debug('Maximal debugging info')
logger.info('Non-error information')
logger.warn('Non-error warning')
logger.error('Non-fatal error')
logger.fatal('Fatal error')
logger.unknown('Most severe')

Когда вы вызываете любой из этих методов, запись может или не может быть записана в журнал, в зависимости от уровня важности записи и уровня журнала; см. Уровень журнала

Запись всегда имеет:

• Уровень важности (обязательный аргумент для add).

• Автоматически созданное временное значение.

И может также иметь:

• Сообщение.

• Имя программы.

Пример:

logger = Logger.new($stdout)
logger.add(Logger::INFO, 'My message.', 'mung')
# => I, [2022-05-07T17:21:46.536234 #20536]  INFO -- mung: My message.

Стандартный формат записи:

"%s, [%s #%d] %5s -- %s: %s\n"

где значения для форматирования:

• Уровень важности (одна буква).

• Временная метка.

• Process идентификатор.

• Уровень важности (слово).

• Имя программы.

• Сообщение.

Вы можете использовать другой формат записи, выполнив следующие действия:

• Установите пользовательский формат proc (влияет на последующие записи); см. formatter=.

• Вызовите любой из методов выше с блоком (влияет только на одну запись). Это может иметь две выгоды:

  • Контекст: блок может оценить весь контекст программы и создать сообщение, зависящее от контекста.

  • Производительность: блок не оценивается, если уровень журнала не позволяет фактически записывать запись:

    logger.error { my_slow_message_generator }
    

    В отличие от строковой формы, где строка всегда оценивается, независимо от уровня журнала:

    logger.error("#{my_slow_message_generator}")
    

Уровень важности

Уровень важности записи журнала имеет два эффекта:

• Определяет, будет ли запись включена в журнал; см. Уровень журнала.

• Указывает любому читателю журнала (человеку или программе) относительную важность записи.

Временная метка

Временная метка для записи журнала генерируется автоматически при создании записи.

Записанная временная метка форматируется методом Time#strftime с использованием следующего формата строки:

'%Y-%m-%dT%H:%M:%S.%6N'

Пример:

logger = Logger.new($stdout)
logger.add(Logger::INFO)
# => I, [2022-05-07T17:04:32.318331 #20536]  INFO -- : nil

Вы можете установить другой формат, используя метод datetime_format=.

Сообщение

Сообщение — это необязательный аргумент метода записи:

logger = Logger.new($stdout)
logger.add(Logger::INFO, 'My message')
# => I, [2022-05-07T18:15:37.647581 #20536]  INFO -- : My message

Для стандартного форматировщика записей, Logger::Formatter, объект сообщения может быть:

• Строка: используется как есть.

• Исключение: message.message используется.

• Что-то ещё: message.inspect используется.

Примечание: Logger::Formatter не экранирует и не очищает сообщение, переданное ему. Разработчики должны понимать, что в сообщении может быть вредоносные данные (ввод пользователя) и должны явно экранировать недоверенные данные.

Вы можете использовать пользовательский форматировщик для экранирования данных сообщения; см. пример в formatter=.

Имя программы

Имя программы — это необязательный аргумент метода записи:

logger = Logger.new($stdout)
logger.add(Logger::INFO, 'My message', 'mung')
# => I, [2022-05-07T18:17:38.084716 #20536]  INFO -- mung: My message

Стандартное имя программы для нового регистратора может быть установлено в вызове Logger.new с помощью необязательного ключевого аргумента progname:

logger = Logger.new('t.log', progname: 'mung')

Стандартное имя программы для существующего регистратора может быть установлено вызовом метода progname=:

logger.progname = 'mung'

Текущее имя программы может быть получено с помощью метода progname:

logger.progname # => "mung"

Уровень журнала

Настройка уровня журнала определяет, будет ли запись фактически записана в журнал на основе уровня важности записи.

Вот определенные уровни важности (от менее важных к более важным):

logger = Logger.new($stdout)
logger.add(Logger::DEBUG, 'Maximal debugging info')
# => D, [2022-05-07T17:57:41.776220 #20536] DEBUG -- : Maximal debugging info
logger.add(Logger::INFO, 'Non-error information')
# => I, [2022-05-07T17:59:14.349167 #20536]  INFO -- : Non-error information
logger.add(Logger::WARN, 'Non-error warning')
# => W, [2022-05-07T18:00:45.337538 #20536]  WARN -- : Non-error warning
logger.add(Logger::ERROR, 'Non-fatal error')
# => E, [2022-05-07T18:02:41.592912 #20536] ERROR -- : Non-fatal error
logger.add(Logger::FATAL, 'Fatal error')
# => F, [2022-05-07T18:05:24.703931 #20536] FATAL -- : Fatal error
logger.add(Logger::UNKNOWN, 'Most severe')
# => A, [2022-05-07T18:07:54.657491 #20536]   ANY -- : Most severe

Стандартная начальная настройка уровня — Logger::DEBUG, наименее строгий уровень, что означает, что все записи должны быть записаны, независимо от уровня важности:

logger = Logger.new($stdout)
logger.level # => 0
logger.add(0, "My message")
# => D, [2022-05-11T15:10:59.773668 #20536] DEBUG -- : My message

Вы можете указать другую настройку в новом регистраторе, используя ключевой аргумент level с соответствующим значением:

logger = Logger.new($stdout, level: Logger::ERROR)
logger = Logger.new($stdout, level: 'error')
logger = Logger.new($stdout, level: :error)
logger.level # => 3

С этим уровнем записи с уровнем важности Logger::ERROR и выше записываются, в то время как записи с более низкими уровнями важности не записываются:

logger = Logger.new($stdout, level: Logger::ERROR)
logger.add(3)
# => E, [2022-05-11T15:17:20.933362 #20536] ERROR -- : nil
logger.add(2) # Silent.

Вы можете установить уровень журнала для существующего регистратора с помощью метода level=:

logger.level = Logger::ERROR

Эти сокращённые методы также устанавливают уровень:

logger.debug! # => 0
logger.info!  # => 1
logger.warn!  # => 2
logger.error! # => 3
logger.fatal! # => 4

Вы можете получить уровень журнала с помощью метода level.

logger.level = Logger::ERROR
logger.level # => 3

Эти методы возвращают, записывается ли данный уровень:

logger.level = Logger::ERROR
logger.debug? # => false
logger.info?  # => false
logger.warn?  # => false
logger.error? # => true
logger.fatal? # => true

Ротация файла File

По умолчанию файл журнала — это один файл, который неограниченно растёт (пока явно не закрыт); ротации файлов нет.

Чтобы поддерживать файлы журналов в управляемом размере, вы можете использовать ротацию файлов журнала, которая использует несколько файлов журнала:

• Каждый файл журнала содержит записи за неперекрывающийся временной интервал.

• Только самый последний файл журнала открыт и активен; остальные закрыты и неактивны.

Ротация на основе размера

Для ротации файлов журнала на основе размера вызовите Logger.new с:

• Аргументом logdev как путём к файлу.

• Аргументом shift_age с положительным целым числом: количество файлов журнала в ротации.

• Аргументом shift_size как положительным целым числом: максимальный размер (в байтах) каждого файла журнала; по умолчанию 1048576 (1 мегабайт).

Примеры:

logger = Logger.new('t.log', 3)           # Three 1-megabyte files.
logger = Logger.new('t.log', 5, 10485760) # Five 10-megabyte files.

Для этих примеров предположим:

logger = Logger.new('t.log', 3)

Запись в новый файл журнала t.log; файл журнала «полный» и готов к ротации, когда новая запись приведет к превышению размера shift_size.

В первый раз, когда t.log полон:

• t.log закрывается и переименовывается в t.log.0.

• Открывается новый файл t.log.

Во второй раз, когда t.log полон:

• +t.log.0 переименовывается как t.log.1.

• t.log закрывается и переименовывается в t.log.0.

• Открывается новый файл t.log.

Каждый последующий раз, когда t.log полон, файлы журнала вращаются:

• t.log.1 удаляется.

• +t.log.0 переименовывается как t.log.1.

• t.log закрывается и переименовывается в t.log.0.

• Открывается новый файл t.log.

Периодическая ротация

Для периодической ротации вызовите Logger.new с:

• Аргументом logdev как путём к файлу.

• Аргументом shift_age как строковым индикатором периода.

Примеры:

logger = Logger.new('t.log', 'daily')   # Rotate log files daily.
logger = Logger.new('t.log', 'weekly')  # Rotate log files weekly.
logger = Logger.new('t.log', 'monthly') # Rotate log files monthly.

Пример:

logger = Logger.new('t.log', 'daily')

Когда заданный период истекает:

• Базовый файл журнала t.log закрывается и переименовывается с датой-основанным суффиксом, например, t.log.20220509.

• Открывается новый файл журнала t.log.

• Ничего не удаляется.

Стандартный формат суффикса — '%Y%m%d', который создаёт суффикс, похожий на указанный выше. Вы можете установить другой формат, используя опцию создания времени shift_period_suffix; см. подробности и рекомендации в Time#strftime.