class Logger

.
see details and suggestions at
shift_period_suffix;
You can set a different format using create-time option
which produces a suffix similar to the one above.
The default format for the suffix is '%Y%m%d',
- Nothing is removed.
- A new log file t.log is opened.
with a date-based suffix such as t.log.20220509.
- The base log file, t.log is closed and renamed
When the given period expires:
logger = Logger.new(‘t.log’, ‘daily’)
Example:
logger = Logger.new(‘t.log’, ‘monthly’) # Rotate log files monthly.
logger = Logger.new(‘t.log’, ‘weekly’) # Rotate log files weekly.
logger = Logger.new(‘t.log’, ‘daily’) # Rotate log files daily.
Examples:
- Argument shift_age as a string period indicator.
- Argument logdev as a file path.
For periodic rotation, call Logger.new with:
=== Periodic Rotation
- A new file t.log is opened.
- t.log is closed and renamed to t.log.0.
- +t.log.0 is renamed as t.log.1.
- t.log.1 is removed.
the log files are rotated:
Each subsequent time that t.log is full,
- A new file t.log is opened.
- t.log is closed and renamed to t.log.0.
- +t.log.0 is renamed as t.log.1.
The second time t.log is full:
- A new file t.log is opened.
- t.log is closed and renamed to t.log.0.
The first time t.log is full:
when a new entry would cause its size to exceed shift_size.
the log file is “full” and ready for rotation
Logging begins in the new log file, t.log;
logger = Logger.new(‘t.log’, 3)
For these examples, suppose:
logger = Logger.new(‘t.log’, 5, 10485760) # Five 10-megabyte files.
logger = Logger.new(‘t.log’, 3) # Three 1-megabyte files.
Examples:
defaults to 1048576 (1 megabyte).
the maximum size (in bytes) of each log file;
- Argument shift_size as a positive integer:
the number of log files to be in the rotation.
- Argument shift_age with a positive integer:
- Argument logdev as a file path.
For size-based log file rotation, call Logger.new with:
=== Size-Based Rotation
the others are closed and inactive.
- Only the most recent log file is open and active;
time interval.
- Each log file has entries for a non-overlapping
you can use log file rotation, which uses multiple log files:
To keep log files to a manageable size,
(until explicitly closed); there is no file rotation.
By default, a log file is a single file that grows indefinitely
== Log File Rotation
logger.fatal? # => true
logger.error? # => true
logger.warn? # => false
logger.info? # => false
logger.debug? # => false
logger.level = Logger::ERROR
level is to be written:
These methods return whether a given
logger.level # => 3
logger.level = Logger::ERROR
You can retrieve the log level with method #level.
logger.fatal! # => 4
logger.error! # => 3
logger.warn! # => 2
logger.info! # => 1
logger.debug! # => 0
These shorthand methods also set the level:
logger.level = Logger::ERROR
with method #level=:
You can set the log level for an existing logger
logger.add(2) # Silent.
# => E, [2022-05-11T15:17:20.933362 #20536] ERROR – : nil
logger.add(3)
logger = Logger.new($stdout, level: Logger::ERROR)
are written, while those with lower severities are not written:
With this level, entries with severity Logger::ERROR and higher
logger.level # => 3
logger = Logger.new($stdout, level: :error)
logger = Logger.new($stdout, level: ‘error’)
logger = Logger.new($stdout, level: Logger::ERROR)
using keyword argument level with an appropriate value:
You can specify a different setting in a new logger
# => D, [2022-05-11T15:10:59.773668 #20536] DEBUG – : My message
logger.add(0, “My message”)
logger.level # => 0
logger = Logger.new($stdout)
which means that all entries are to be written, regardless of severity:
The default initial level setting is Logger::DEBUG, the lowest level,
# => A, [2022-05-07T18:07:54.657491 #20536] ANY – : Most severe
logger.add(Logger::UNKNOWN, ‘Most severe’)
# => F, [2022-05-07T18:05:24.703931 #20536] FATAL – : Fatal error
logger.add(Logger::FATAL, ‘Fatal error’)
# => E, [2022-05-07T18:02:41.592912 #20536] ERROR – : Non-fatal error
logger.add(Logger::ERROR, ‘Non-fatal error’)
# => W, [2022-05-07T18:00:45.337538 #20536] WARN – : Non-error warning
logger.add(Logger::WARN, ‘Non-error warning’)
# => I, [2022-05-07T17:59:14.349167 #20536] INFO – : Non-error information
logger.add(Logger::INFO, ‘Non-error information’)
# => D, [2022-05-07T17:57:41.776220 #20536] DEBUG – : Maximal debugging info
logger.add(Logger::DEBUG, ‘Maximal debugging info’)
logger = Logger.new($stdout)
These are the defined severities (least severe to most severe):
written to the log, based on the entry’s severity.
The log level setting determines whether an entry is actually
== Log Level
logger.progname # => “mung”
:
The current program name may be retrieved with method
logger.progname = ‘mung’
by a call to method #progname=:
The default program name for an existing logger may be set
logger = Logger.new(‘t.log’, progname: ‘mung’)
Logger.new via optional keyword argument progname:
The default program name for a new logger may be set in the call to
# => I, [2022-05-07T18:17:38.084716 #20536] INFO – mung: My message
logger.add(Logger::INFO, ‘My message’, ‘mung’)
logger = Logger.new($stdout)
The program name is an optional argument to an entry method:
=== Program Name
see the example at formatter=.
You can use a custom formatter to escape message data;
may be in the message, and should explicitly escape untrusted data.
Developers should be aware that malicious data (user input)
the message passed to it.
Note: Logger::Formatter does not escape or sanitize
- Anything else: message.inspect is used.
- An Exception: message.message is used.
- A string: used as-is.
the message object may be:
For the default entry formatter, Logger::Formatter,
# => I, [2022-05-07T18:15:37.647581 #20536] INFO – : My message
logger.add(Logger::INFO, ‘My message’)
logger = Logger.new($stdout)
The message is an optional argument to an entry method:
=== Message
You can set a different format using method #datetime_format=.
# => I, [2022-05-07T17:04:32.318331 #20536] INFO – : nil
logger.add(Logger::INFO)
logger = Logger.new($stdout)
Example:
‘%Y-%m-%dT%H:%M:%S.%6N’
using this format string:
The logged timestamp is formatted by method
when the entry is created.
The timestamp for a log entry is generated automatically
=== Timestamp
the relative importance of the entry.
- Indicates to any log reader (whether a person or a program)
see Log Level.
- Determines whether the entry is selected for inclusion in the log;
The severity of a log entry has two effects:
=== Severity
logger.error(“#{my_slow_message_generator}”)
always evaluated, regardless of the log level:
Contrast this with the string form, where the string is
logger.error { my_slow_message_generator }
permits the entry actually to be written:
- Performance: the block is not evaluated unless the log level
and create a context-dependent message.
- Context: the block can evaluate the entire program context
Doing so can have two benefits:
(affects only the one entry).
- Calling any of the methods above with a block
see formatter=.
- Setting a custom format proc (affects following entries);
You can use a different entry format by:
- Message.
- Program name.
- Severity (word).
- Process id.
- Timestamp.
- Severity (one letter).
where the values to be formatted are:
“%s, [%s #%d] %5s – %s: %sn”
The default format for an entry is:
# => I, [2022-05-07T17:21:46.536234 #20536] INFO – mung: My message.
logger.add(Logger::INFO, ‘My message.’, ‘mung’)
logger = Logger.new($stdout)
Example:
- A program name.
- A message.
And may also have:
- An automatically created timestamp.
- A severity (the required argument to #add).
An entry always has:
see {Log Level}[rdoc-ref:Logger@Log+Level]
depending on the entry’s severity and on the log level;
the entry may or may not be written to the log,
When you call any of these methods,
logger.unknown(‘Most severe’)
logger.fatal(‘Fatal error’)
logger.error(‘Non-fatal error’)
logger.warn(‘Non-error warning’)
logger.info(‘Non-error information’)
logger.debug(‘Maximal debugging info’)
These shorthand methods also add entries:
logger.add(Logger::UNKNOWN, ‘Most severe’)
logger.add(Logger::FATAL, ‘Fatal error’)
logger.add(Logger::ERROR, ‘Non-fatal error’)
logger.add(Logger::WARN, ‘Non-error warning’)
logger.add(Logger::INFO, ‘Non-error information’)
logger.add(Logger::DEBUG, ‘Maximal debugging info’)
You can add entries with method Logger#add:
== Entries
logger.close
Close the log with Logger#close:
logger.add(Logger::UNKNOWN, ‘Most severe’)
logger.add(Logger::FATAL, ‘Fatal error’)
logger.add(Logger::ERROR, ‘Non-fatal error’)
logger.add(Logger::WARN, ‘Non-error warning’)
logger.add(Logger::INFO, ‘Non-error information’)
logger.add(Logger::DEBUG, ‘Maximal debugging info’)
Add entries (level, message) with Logger#add:
logger = Logger.new($stdout)
# Log to an IO stream.
logger = Logger.new(‘t.log’, ‘daily’)
# Period-based rotated logging: daily (also allowed: ‘weekly’, ‘monthly’).
logger = Logger.new(‘t.log’, 3, 10485760)
# Size-based rotated logging: 3 10-megabyte files.
logger = Logger.new(‘t.log’)
# Single log file.
Create a log with Logger.new:
== Synopsis
require ‘logger’
All examples on this page assume that Logger has been required:
== About the Examples
that provides a record of the program’s activities.
Each such log contains a chronological sequence of entries
for your program.
you can use to create one or more
Class Logger provides a simple but sophisticated logging utility that