класс 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 идентификатор.

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

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

• Сообщение.

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

• Установка пользовательского формата (влияет на последующие записи); см. 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.