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

где форматируемые значения — это:

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

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

• Идентификатор процесса.

• Уровень серьёзности (словом).

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

• Сообщение.

Можно использовать другой формат записи:

• Задав пользовательский 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.