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