# frozen_string_literal: true
# logger.rb - simple logging utility
# Copyright (C) 2000-2003, 2005, 2008, 2011 NAKAMURA, Hiroshi <nahi@ruby-lang.org>.
# Documentation:: NAKAMURA, Hiroshi and Gavin Sinclair
# You can redistribute it and/or modify it under the same terms of Ruby's
# license; either the dual license version in 2003, or any later version.
# A simple system for logging messages. See Logger for more documentation.
require_relative 'logger/version'
require_relative 'logger/formatter'
require_relative 'logger/log_device'
require_relative 'logger/severity'
require_relative 'logger/errors'
# The Logger class provides a simple but sophisticated logging utility that
# you can use to output messages.
# 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.
# +UNKNOWN+:: An unknown message that should always be logged.
# +FATAL+:: An unhandleable error that results in a program crash.
# +ERROR+:: A handleable error condition.
# +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
# When you are developing the system, however, you probably
# want to know about the program's internal state, and would set the Logger to
# *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)
# This creates a Logger that outputs to the standard output stream, with a
# logger = Logger.new(STDOUT)
# logger.level = Logger::WARN
# logger.debug("Created logger")
# logger.info("Program started")
# logger.warn("Nothing to do!")
# path = "a_non_existent_file"
# File.foreach(path) do |line|
# unless line =~ /^(\w+) = (.*)$/
# logger.error("Line in wrong format: #{line.chomp}")
# logger.fatal("Caught exception; exiting")
# 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
# 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.
# === How to create a logger
# The options below give you various choices, in more or less increasing
# 1. Create a logger which logs messages to STDERR/STDOUT.
# logger = Logger.new(STDERR)
# logger = Logger.new(STDOUT)
# 2. Create a logger for the file which has the specified name.
# logger = Logger.new('logfile.log')
# 3. Create a logger for the specified file.
# 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)
# 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.
# logger = Logger.new('foo.log', 10, 1024000)
# 5. Create a logger which ages the logfile daily/weekly/monthly.
# logger = Logger.new('foo.log', 'daily')
# logger = Logger.new('foo.log', 'weekly')
# logger = Logger.new('foo.log', 'monthly')
# === How to log a message
# 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
# logger.fatal { "Argument 'foo' not given." }
# 2. Message as a string.
# logger.error "Argument #{@foo} mismatch."
# logger.info('initialize') { "Initializing..." }
# logger.add(Logger::FATAL) { 'Fatal error!' }
# 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:
# logger.debug { "This is a " + potentially + " expensive operation" }
# 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:
# logger.debug("This is a " + potentially + " expensive operation")
# Here, the string concatenation is done every time, even if the log
# level is not set to show the debug message.
# === How to close a logger
# === Setting severity threshold
# logger.sev_threshold = Logger::WARN
# 2. Log4r (somewhat) compatible interface.
# logger.level = Logger::INFO
# # DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN
# 3. Symbol or String (case insensitive)
# # :debug < :info < :warn < :error < :fatal < :unknown
# Logger.new(logdev, level: Logger::INFO)
# Logger.new(logdev, level: :info)
# Logger.new(logdev, level: 'INFO')
# Log messages are rendered in the output stream in a certain format by
# default. The default format and a sample are shown below:
# SeverityID, [DateTime #pid] SeverityLabel -- ProgName: message
# I, [1999-03-03T02:34:24.895701 #19074] INFO -- Main: info.
# You may change the date and time format via #datetime_format=.
# logger.datetime_format = '%Y-%m-%d %H:%M:%S'
# # e.g. "2004-01-03 00:54:26"
# or via the constructor.
# Logger.new(logdev, datetime_format: '%Y-%m-%d %H:%M:%S')
# Or, you may change the overall format via the #formatter= method.
# logger.formatter = proc do |severity, datetime, progname, msg|
# "#{datetime}: #{msg}\n"
# # e.g. "2005-09-22 08:51:08 +0900: hello world"
# or via the constructor.
# Logger.new(logdev, formatter: proc {|severity, datetime, progname, msg|
# "#{datetime}: #{msg}\n"
name = File.basename(__FILE__)
ProgName = "#{name}/#{rev}"
# Logging severity threshold (e.g. <tt>Logger::INFO</tt>).
# Set logging severity threshold.
# +severity+:: The Severity of the log message.
if severity.is_a?(Integer)
case severity.to_s.downcase
raise ArgumentError, "invalid log level: #{severity}"
# Program name to include in log messages.
# +datetime_format+:: A string suitable for passing to +strftime+.
def datetime_format=(datetime_format)
@default_formatter.datetime_format = datetime_format
# Returns the date format being used. See #datetime_format=
@default_formatter.datetime_format
# Logging formatter, as a +Proc+ that will take four arguments and
# return the formatted message. The arguments are:
# +severity+:: The Severity of the log message.
# +time+:: A Time instance representing when the message was logged.
# +progname+:: The #progname configured, or passed to the logger method.
# +msg+:: The _Object_ the user passed to the log message; not necessarily a
# The block should return an Object that can be written to the logging
# device via +write+. The default formatter is used when no formatter is
alias sev_threshold level
alias sev_threshold= level=
# Returns +true+ if and only if the current severity level allows for the printing of
def debug?; level <= DEBUG; end
# Sets the severity to DEBUG.
def debug!; self.level = DEBUG; end
# Returns +true+ if and only if the current severity level allows for the printing of
def info?; level <= INFO; end
# Sets the severity to INFO.
def info!; self.level = INFO; end
# Returns +true+ if and only if the current severity level allows for the printing of
def warn?; level <= WARN; end
# Sets the severity to WARN.
def warn!; self.level = WARN; end
# Returns +true+ if and only if the current severity level allows for the printing of
def error?; level <= ERROR; end
# Sets the severity to ERROR.
def error!; self.level = ERROR; end
# Returns +true+ if and only if the current severity level allows for the printing of
def fatal?; level <= FATAL; end
# Sets the severity to FATAL.
def fatal!; self.level = FATAL; end
# 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')
# The log device. This is a filename (String), IO object (typically
# +STDOUT+, +STDERR+, or an open file), +nil+ (it writes nothing) or
# +File::NULL+ (same as +nil+).
# Number of old log files to keep, *or* frequency of rotation (+daily+,
# +weekly+ or +monthly+). Default value is 0, which disables log file
# Maximum logfile size in bytes (only applies when +shift_age+ is a positive
# Integer). Defaults to +1048576+ (1MB).
# Logging severity threshold. Default values is Logger::DEBUG.
# Program name to include in log messages. Default value is nil.
# Logging formatter. Default values is an instance of Logger::Formatter.
# Date and time format. Default value is '%Y-%m-%d %H:%M:%S'.
# Use binary mode on the log device. Default value is false.
# +shift_period_suffix+::
# The log file suffix format for +daily+, +weekly+ or +monthly+ rotation.
def initialize(logdev, shift_age = 0, shift_size = 1048576, level: DEBUG,
progname: nil, formatter: nil, datetime_format: nil,
binmode: false, shift_period_suffix: '%Y%m%d')
@default_formatter = Formatter.new
self.datetime_format = datetime_format
self.formatter = formatter
if logdev && logdev != File::NULL
@logdev = LogDevice.new(logdev, shift_age: shift_age,
shift_period_suffix: shift_period_suffix,
# The log device. This is a filename (String) or IO object (typically
# +STDOUT+, +STDERR+, or an open file). reopen the same filename if
# it is +nil+, do nothing for IO. Default is +nil+.
# Logger#add(severity, message = nil, progname = nil) { ... }
# Severity. Constants are defined in Logger namespace: +DEBUG+, +INFO+,
# +WARN+, +ERROR+, +FATAL+, or +UNKNOWN+.
# The log message. A String or Exception.
# Program name string. Can be omitted. Treated as a message if no
# +message+ and +block+ are given.
# Can be omitted. Called to get a message string if +message+ is nil.
# When the given severity is not high enough (for this particular logger),
# log no message, and return +true+.
# Log a message if the given severity is high enough. This is the generic
# logging method. Users will be more inclined to use #debug, #info, #warn,
# <b>Message format</b>: +message+ can be any object, but it has to be
# converted to a String in order to log it. Generally, +inspect+ is used
# if the given object is not a String.
# A special case is an +Exception+ object, which will be printed in detail,
# including message, class, and backtrace. See #msg2str for the
# implementation if required.
# * Logfile is not locked.
# * Append open does not need to lock file.
# * If the OS supports multi I/O, records possibly may be mixed.
def add(severity, message = nil, progname = nil)
if @logdev.nil? or severity < level
format_message(format_severity(severity), Time.now, progname, message))
# Dump given message to the log device without any formatting. If no log
# device exists, return +nil+.
# See #info for more information.
def debug(progname = nil, &block)
add(DEBUG, nil, progname, &block)
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
