From 90d8b7219e26135cb1003ebfc5884f132ba39867 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Thu, 12 May 2022 07:27:52 -0500 Subject: [PATCH] [ruby/logger] Enhanced RDoc for Logger https://github.com/ruby/logger/commit/16556d06d1 --- lib/logger.rb | 447 ++++++++++++++++++++++++++++--------------- lib/logger/errors.rb | 2 +- 2 files changed, 297 insertions(+), 152 deletions(-) diff --git a/lib/logger.rb b/lib/logger.rb index 7d55f62f30..e66ec2ee21 100644 --- a/lib/logger.rb +++ b/lib/logger.rb @@ -19,216 +19,352 @@ require_relative 'logger/log_device' require_relative 'logger/severity' require_relative 'logger/errors' -# == Description +# \Class \Logger provides a simple but sophisticated logging utility that +# you can use to create one or more +# {event logs}[https://en.wikipedia.org/wiki/Logging_(software)#Event_logs] +# for your program. +# Each such log contains a chronological sequence of entries +# that provides a record of the program's activities. # -# The Logger class provides a simple but sophisticated logging utility that -# you can use to output messages. +# == About the Examples # -# The messages have associated levels, such as +INFO+ or +ERROR+ that indicate -# their importance. You can then give the Logger a level, and only messages -# at that level or higher will be printed. -# -# The levels are: -# -# +UNKNOWN+:: An unknown message that should always be logged. -# +FATAL+:: An unhandleable error that results in a program crash. -# +ERROR+:: A handleable error condition. -# +WARN+:: A warning. -# +INFO+:: Generic (useful) information about system operation. -# +DEBUG+:: Low-level information for developers. -# -# For instance, in a production system, you may have your Logger set to -# +INFO+ or even +WARN+. -# When you are developing the system, however, you probably -# want to know about the program's internal state, and would set the Logger to -# +DEBUG+. -# -# *Note*: Logger does not escape or sanitize any messages passed to it. -# Developers should be aware of when potentially malicious data (user-input) -# is passed to Logger, and manually escape the untrusted data: -# -# logger.info("User-input: #{input.dump}") -# logger.info("User-input: %p" % input) -# -# You can use #formatter= for escaping all data. -# -# original_formatter = Logger::Formatter.new -# logger.formatter = proc { |severity, datetime, progname, msg| -# original_formatter.call(severity, datetime, progname, msg.dump) -# } -# logger.info(input) -# -# === Example -# -# This creates a Logger that outputs to the standard output stream, with a -# level of +WARN+: +# All examples on this page assume that \Logger has been required: # # require 'logger' # -# logger = Logger.new(STDOUT) -# logger.level = Logger::WARN +# == Synopsis # -# logger.debug("Created logger") -# logger.info("Program started") -# logger.warn("Nothing to do!") +# Create a log with Logger.new: # -# path = "a_non_existent_file" +# # Single log file. +# logger = Logger.new('t.log') +# # Size-based rotated log: 3 10-megabyte files. +# logger = Logger.new('t.log', 3, 10485760) +# # Period-based rotated log: daily (also allowed: 'weekly', 'monthly'). +# logger = Logger.new('t.log', 'daily') # -# begin -# File.foreach(path) do |line| -# unless line =~ /^(\w+) = (.*)$/ -# logger.error("Line in wrong format: #{line.chomp}") -# end -# end -# rescue => err -# logger.fatal("Caught exception; exiting") -# logger.fatal(err) -# end +# Add entries (level, message) with Logger#add: # -# Because the Logger's level is set to +WARN+, only the warning, error, and -# fatal messages are recorded. The debug and info messages are silently -# discarded. +# 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') # -# === Features +# There are also these shorthand methods: # -# There are several interesting features that Logger provides, like -# auto-rolling of log files, setting the format of log messages, and -# specifying a program name in conjunction with the message. The next section -# shows you how to achieve these things. +# 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') # +# For each method in the two groups immediately above, +# you can omit the string message and provide a block instead. +# Doing so can have two benefits: # -# == HOWTOs +# - Context: the block can evaluate the entire program context +# and create a context-dependent message. +# - Performance: the block is not evaluated unless the log level +# permits the entry actually to be written: # -# === How to create a logger +# logger.error { my_slow_message_generator } # -# The options below give you various choices, in more or less increasing -# complexity. +# Contrast this with the string form, where the string is +# always evaluated, regardless of the log level: # -# 1. Create a logger which logs messages to STDERR/STDOUT. +# logger.error("#{my_slow_message_generator}") # -# logger = Logger.new(STDERR) -# logger = Logger.new(STDOUT) +# Close the log with Logger#close: # -# 2. Create a logger for the file which has the specified name. +# logger.close # -# logger = Logger.new('logfile.log') +# == Log Stream # -# 3. Create a logger for the specified file. +# When you create a \Logger instance, you specify an IO stream +# for the logger's output, usually either an open File object +# or an IO object such as $stdout or $stderr. # -# file = File.open('foo.log', File::WRONLY | File::APPEND) -# # To create new logfile, add File::CREAT like: -# # file = File.open('foo.log', File::WRONLY | File::APPEND | File::CREAT) -# logger = Logger.new(file) +# == Entries # -# 4. Create a logger which ages the logfile once it reaches a certain size. -# Leave 10 "old" log files where each file is about 1,024,000 bytes. +# When you call instance method #add (or its alias #log), +# an entry may (or may not) be written to the log; +# see {Log Level}[rdoc-ref:Logger@Log+Level] # -# logger = Logger.new('foo.log', 10, 1024000) +# An entry always has: # -# 5. Create a logger which ages the logfile daily/weekly/monthly. +# - A severity (the required argument to #add). +# - An automatically created timestamp. # -# logger = Logger.new('foo.log', 'daily') -# logger = Logger.new('foo.log', 'weekly') -# logger = Logger.new('foo.log', 'monthly') +# And may also have: # -# === How to log a message +# - A message. +# - A program name. # -# Notice the different methods (+fatal+, +error+, +info+) being used to log -# messages of various levels? Other methods in this family are +warn+ and -# +debug+. +add+ is used below to log a message of an arbitrary (perhaps -# dynamic) level. +# Example: # -# 1. Message in a block. +# logger = Logger.new($stdout) +# logger.add(Logger::INFO, 'msg', 'progname') +# # => I, [2022-05-07T17:21:46.536234 #20536] INFO -- progname: msg # -# logger.fatal { "Argument 'foo' not given." } +# The default format for an entry is: # -# 2. Message as a string. +# "%s, [%s #%d] %5s -- %s: %s\n" # -# logger.error "Argument #{@foo} mismatch." +# where the values to be formatted are: # -# 3. With progname. +# - \Severity (one letter). +# - Timestamp. +# - Timezone. +# - \Severity (word). +# - Program name. +# - Message. # -# logger.info('initialize') { "Initializing..." } +# You can use a different entry format by: # -# 4. With severity. +# - Calling #add with a block (affects only the one entry). +# - Setting a format proc with method +# {formatter=}[Logger.html#attribute-i-formatter] +# (affects following entries). # -# logger.add(Logger::FATAL) { 'Fatal error!' } +# === \Severity # -# The block form allows you to create potentially complex log messages, -# but to delay their evaluation until and unless the message is -# logged. For example, if we have the following: +# The severity of a log entry, which is specified in the call to #add, +# does two things: # -# logger.debug { "This is a " + potentially + " expensive operation" } +# - Determines whether the entry is selected for inclusion in the log; +# see {Log Level}[rdoc-ref:Logger@Log+Level]. +# - Indicates to any log reader (whether a person or a program) +# the relative importance of the entry. # -# If the logger's level is +INFO+ or higher, no debug messages will be logged, -# and the entire block will not even be evaluated. Compare to this: +# === Timestamp # -# logger.debug("This is a " + potentially + " expensive operation") +# The timestamp for a log entry is generated automatically +# when the entry is created (by a call to #add). # -# Here, the string concatenation is done every time, even if the log -# level is not set to show the debug message. +# The logged timestamp is formatted by method +# {Time#strftime}[https://docs.ruby-lang.org/en/master/Time.html#method-i-strftime] +# using this format string: # -# === How to close a logger +# '%Y-%m-%dT%H:%M:%S.%6N' # -# logger.close +# Example: # -# === Setting severity threshold +# logger = Logger.new($stdout) +# logger.add(Logger::INFO) +# # => I, [2022-05-07T17:04:32.318331 #20536] INFO -- : nil # -# 1. Original interface. +# You can set a different format using method #datetime_format=. # -# logger.sev_threshold = Logger::WARN +# === Message # -# 2. Log4r (somewhat) compatible interface. +# The message is an optional argument to method #add: # -# logger.level = Logger::INFO +# logger = Logger.new($stdout) +# logger.add(Logger::INFO, 'My message') +# # => I, [2022-05-07T18:15:37.647581 #20536] INFO -- : My message # -# # DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN +# The message object may be a string, or an object that can be converted +# to a string. # -# 3. Symbol or String (case insensitive) +# *Note*: \Logger does not escape or sanitize any messages passed to it. +# Developers should be aware that malicious data (user input) +# may be passed to \Logger, and should explicitly escape untrusted data. # -# logger.level = :info -# logger.level = 'INFO' +# You can use a custom formatter to escape message data; +# this formatter uses +# {String#dump}[https://ruby-doc.org/core-3.1.2/String.html#method-i-dump] +# to escape the message string: # -# # :debug < :info < :warn < :error < :fatal < :unknown +# original_formatter = logger.formatter || Logger::Formatter.new +# logger.formatter = proc { |sev, time, progname, msg| +# original_formatter.call(sev, time, progname, msg.dump) +# } +# logger.info(input) # -# 4. Constructor +# === Program Name # -# Logger.new(logdev, level: Logger::INFO) -# Logger.new(logdev, level: :info) -# Logger.new(logdev, level: 'INFO') +# The program name is an optional argument to method #add: # -# == Format +# logger = Logger.new($stdout) +# logger.add(Logger::INFO, 'My message', 'mung') +# # => I, [2022-05-07T18:17:38.084716 #20536] INFO -- mung: My message # -# Log messages are rendered in the output stream in a certain format by -# default. The default format and a sample are shown below: +# The default program name for a new logger may be set in the call to +# Logger.new via optional keyword argument +progname+: # -# Log format: -# SeverityID, [DateTime #pid] SeverityLabel -- ProgName: message +# logger = Logger.new('t.log', progname: 'mung') # -# Log sample: -# I, [1999-03-03T02:34:24.895701 #19074] INFO -- Main: info. +# The default program name for an existing logger may be set +# by a call to method #progname=: # -# You may change the date and time format via #datetime_format=. +# logger.progname = 'mung' # -# logger.datetime_format = '%Y-%m-%d %H:%M:%S' -# # e.g. "2004-01-03 00:54:26" +# The current program name may be retrieved with method +# {progname}[Logger.html#attribute-i-progname]: # -# or via the constructor. +# == Log Level # -# Logger.new(logdev, datetime_format: '%Y-%m-%d %H:%M:%S') +# The log level setting determines whether an entry is actually +# written to the log, based on the entry's severity. # -# Or, you may change the overall format via the #formatter= method. +# These are the defined severities (least severe to most severe): # -# logger.formatter = proc do |severity, datetime, progname, msg| -# "#{datetime}: #{msg}\n" -# end -# # e.g. "2005-09-22 08:51:08 +0900: hello world" +# 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 # -# or via the constructor. +# The default initial level setting is Logger::DEBUG, the lowest level, +# which means that all entries are to be written, regardless of severity: # -# Logger.new(logdev, formatter: proc {|severity, datetime, progname, msg| -# "#{datetime}: #{msg}\n" -# }) +# logger = Logger.new($stdout) +# logger.level # => 0 +# logger.add(0, "My message") +# # => D, [2022-05-11T15:10:59.773668 #20536] DEBUG -- : My message +# +# You can specify a different setting in a new log +# using keyword argument +level+ with an appropriate value: +# +# logger = Logger.new($stdout, level: Logger::ERROR) +# logger = Logger.new($stdout, level: 'error') +# logger = Logger.new($stdout, level: :error) +# logger.level # => 3 +# +# With this level, entries with severity Logger::ERROR and higher +# are written, while those with lower severities are not written: +# +# logger = Logger.new($stdout) +# logger.add(3) +# # =? E, [2022-05-11T15:17:20.933362 #20536] ERROR -- : nil +# logger.add(2) # Silent. +# +# You can set the log level for an existing logger +# with method #level=: +# +# logger.level = Logger::ERROR +# +# There are also these shorthand methods for setting the level: +# +# logger.debug! # => 0 +# logger.info! # => 1 +# logger.warn! # => 2 +# logger.error! # => 3 +# logger.fatal! # => 4 +# +# You can retrieve the log level with method +# {level}[Logger.html#attribute-i-level]: +# +# logger.level = 3 +# logger.level # => 3 +# +# There are also these methods for determining whether a given +# level is to be written: +# +# logger.level = 3 +# logger.debug? # => false +# logger.info? # => false +# logger.warn? # => false +# logger.error? # => true +# logger.fatal? # => true +# +# == Log File Rotation +# +# By default, a log file is a single file that grows indefinitely +# (until explicitly closed); there is no file rotation. +# +# To keep log files to a manageable size, +# you can use _log_ _file_ _rotation_, which uses multiple log files: +# +# - Each log file has entries for a non-overlapping +# time interval. +# - Only the most recent log file is open and active; +# the others are closed and inactive. +# +# === Size-Based Rotation +# +# For size-based log file rotation, call Logger.new with: +# +# - Argument +logdev+ as a file path. +# - Argument +shift_age+ with a positive integer: +# the number of log files to be in the rotation. +# - Argument +shift_size+ as a positive integer: +# the maximum size (in bytes) of each log file; +# defaults to 1048576 (1 megabyte). +# +# Examples: +# +# logger = Logger.new('t.log', 3) # Three 1-megabyte files. +# logger = Logger.new('t.log', 5, 10485760) # Five 10-megabyte files. +# +# For these examples, suppose: +# +# logger = Logger.new('t.log', 3) +# +# Logging begins in the new log file, +t.log+; +# the log file is "full" and ready for rotation +# when a new entry would cause its size to exceed +shift_size+. +# +# The first time +t.log+ is full: +# +# - +t.log+ is closed and renamed to +t.log.0+. +# - A new file +t.log+ is opened. +# +# The second time +t.log+ is full: +# +# - +t.log.0 is renamed as +t.log.1+. +# - +t.log+ is closed and renamed to +t.log.0+. +# - A new file +t.log+ is opened. +# +# Each subsequent time that +t.log+ is full, +# the log files are rotated: +# +# - +t.log.1+ is removed. +# - +t.log.0 is renamed as +t.log.1+. +# - +t.log+ is closed and renamed to +t.log.0+. +# - A new file +t.log+ is opened. +# +# === Periodic Rotation +# +# For periodic rotation, call Logger.new with: +# +# - Argument +logdev+ as a file path. +# - Argument +shift_age+ as a string period indicator. +# +# Examples: +# +# 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. +# +# Example: +# +# logger = Logger.new('t.log', 'daily') +# +# When the given period expires: +# +# - The base log file, +t.log+ is closed and renamed +# with a date-based suffix such as +t.log.20220509+. +# - A new log file +t.log+ is opened. +# - Nothing is removed. +# +# The default format for the suffix is '%Y%m%d', +# which produces a suffix similar to the one above. +# You can set a different format using create-time option +# +shift_period_suffix+; +# see details and suggestions at +# {Time#strftime}[https://docs.ruby-lang.org/en/master/Time.html#method-i-strftime]. # class Logger _, name, rev = %w$Id$ @@ -340,12 +476,21 @@ class Logger # # :call-seq: - # Logger.new(logdev, shift_age = 0, shift_size = 1048576) - # Logger.new(logdev, shift_age = 'weekly') - # Logger.new(logdev, level: :info) - # Logger.new(logdev, progname: 'progname') - # Logger.new(logdev, formatter: formatter) - # Logger.new(logdev, datetime_format: '%Y-%m-%d %H:%M:%S') + # Logger.new(logdev, shift_age = 0, shift_size = 1048576, **options) + # Logger.new(logdev, shift_age = 'weekly', **options) + # + # With the single argument +logdev+, + # returns a new logger with all default options: + # + # Logger.new('t.log') # => # + # + # Argument +logdev+ must be one of: + # + # - A string filepath: entries are to be written + # to the file at that path. + # - An IO stream (typically +$stdout+, +$stderr+. or an open file): + # entries are to be written to the given stream. + # - +nil+ or +File::NULL+: no entries are to be written. # # === Args # diff --git a/lib/logger/errors.rb b/lib/logger/errors.rb index e8925e14ac..88581793f0 100644 --- a/lib/logger/errors.rb +++ b/lib/logger/errors.rb @@ -1,7 +1,7 @@ # frozen_string_literal: true -# not used after 1.2.7. just for compat. class Logger + # not used after 1.2.7. just for compat. class Error < RuntimeError # :nodoc: end class ShiftingError < Error # :nodoc: