Logger
Parent:ObjectIncluded modules:Logger::Severity
描述
Logger 类提供了一个简单但复杂的日志实用程序,可用于输出消息。
这些消息具有关联的级别,例如INFO
或者ERROR
表示它们的重要性。然后您可以给Logger一个级别,并且只会打印该级别或更高级别的消息。
这些级别是:
UNKNOWN
应始终记录一条未知消息。
FATAL
导致程序崩溃的无法解决的错误。
ERROR
可处理的错误情况。
WARN
一个警告。
INFO
关于系统操作的通用(有用)信息。
DEBUG
针对开发人员的低级信息。
例如,在生产系统中,您可能会将您的记录器设置为INFO
或甚至WARN
。但是,在开发系统时,您可能想知道程序的内部状态,并将Logger设置为DEBUG
。
注意:记录器不会转移或清理传递给它的任何消息。开发人员应该知道何时将潜在的恶意数据(用户输入)传递给Logger,并手动转义不可信数据:
logger.info("User-input: #{input.dump}")
logger.info("User-input: %p" % input)
您可以使用formatter =来转义所有数据。
original_formatter = Logger::Formatter.new
logger.formatter = proc { |severity, datetime, progname, msg|
original_formatter.call(severity, datetime, progname, msg.dump)
}
logger.info(input)
例
这将创建一个输出到标准输出流的记录器,其级别为WARN
:
require 'logger'
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"
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
由于记录器的级别设置为WARN
,仅记录警告,错误和致命消息。调试和信息消息被默默丢弃。
Features
Logger 提供了一些有趣的功能,例如自动滚动日志文件,设置日志消息的格式,以及与消息一起指定程序名称。下一节将向您介绍如何实现这些目标。
HOWTOs
如何创建一个记录器
以下选项为您提供各种选择,或多或少地增加复杂性。
- 创建一个将消息记录到STDERR / STDOUT的记录器。logger = Logger.new(STDERR)logger = Logger.new(STDOUT)
- 为具有指定名称的文件创建一个记录器。
logger = Logger.new('logfile.log')
- 为指定的文件创建一个记录器。file = File.open('foo.log',File :: WRONLY | File :: APPEND)#要创建新的(并删除旧的)日志文件,请添加File :: CREAT,如下所示:#file = File.open('foo .log',File :: WRONLY | File :: APPEND | File :: CREAT)logger = Logger.new(file)
- 创建一个日志记录器,在日志文件达到特定大小后将其老化。保留10个“旧”日志文件,其中每个文件约为1,024,000字节。
logger = Logger.new('foo.log', 10, 1024000)
- 创建一个日志记录器,使日志文件每天/每周/每月变老。logger = logger.new('foo.log','daily')logger = Logger.new('foo.log','weekly')logger = Logger.new('foo.log','monthly')
如何记录一个message
注意到被用来记录各种等级的不同方法(fatal
,error
,info
)?在这个家庭的其他方法是warn
和debug
。add
在下面用于记录任意(可能是动态)级别的消息。
1. 消息在块中。
logger.fatal { "Argument 'foo' not given." }
2. 消息为字符串。
logger.error "Argument #{@foo} mismatch."
3. 用程序名。
logger.info('initialize') { "Initializing..." }
4. 严重。
logger.add(Logger::FATAL) { 'Fatal error!' }
块表单允许您创建可能复杂的日志消息,但延迟其评估直至消息被记录。例如,如果我们有以下内容:
logger.debug { "This is a " + potentially + " expensive operation" }
如果记录器的级别是INFO
或更高,则不会记录调试消息,甚至不会评估整个块。与此比较:
logger.debug("This is a " + potentially + " expensive operation")
在这里,每次都会完成字符串连接,即使日志级别未设置为显示调试消息。
如何关闭日志记录器
logger.close
设置严重性阈值
1. 原始界面。
logger.sev_threshold = Logger::WARN
2. Log4r(somewhat)兼容的界面。
logger.level = Logger :: INFO
#DEBUG <INFO <WARN <ERROR <FATAL <UNKNOWN
3. 符号或字符串(不区分大小写)
logger.level = :info logger.level = 'INFO' # :debug < :info < :warn < :error < :fatal < :unknown
4. 构造函数
Logger.new(logdev, level: Logger::INFO) Logger.new(logdev, level: :info) Logger.new(logdev, level: 'INFO')
格式
Log消息以特定格式呈现在输出流中默认。默认格式和示例如下所示:
日志格式:
SeverityID, [DateTime #pid] SeverityLabel -- ProgName: message
示例:
I, [1999-03-03T02:34:24.895701 #19074] INFO -- Main: info.
您可以通过datetime_format = .logger.datetime_format =
logger.datetime_format = '%Y-%m-%d %H:%M:%S'
# e.g. "2004-01-03 00:54:26"
或通过以下方式更改日期和时间格式构造函数
Logger.new(logdev, datetime_format: '%Y-%m-%d %H:%M:%S')
或者,你可以通过formatter = method.来改变整体格式
logger.formatter = proc do |severity, datetime, progname, msg|
"#{datetime}: #{msg}\n"
end
# e.g. "2005-09-22 08:51:08 +0900: hello world"
或通过构造函数。
Logger.new(logdev, formatter: proc {|severity, datetime, progname, msg|
"#{datetime}: #{msg}\n"
})
常量
PROGNAME
SEV_LABEL
记录的严重性标签(最多5个字符)。
版本
属性
formatter[RW]
记录格式化程序,作为将采用四个参数并返回格式化消息的Proc。 参数是:
严重(severity) |
---|
日志消息的严重性。 |
时间(time) |
表示消息记录时间的Time实例。 |
progname |
程序名已配置,或传递给记录器方法。 |
msg |
用户传递给日志消息的对象;不一定是一个字符串。 |
该块应该返回一个可以通过写入写入日志设备的对象。 未设置格式化程序时使用默认格式化程序。
level[R]
记录严重性阈值(例如Logger::INFO)。
progname[RW]
要包含在日志消息中的程序名称。
sev_threshold[R]
记录严重性阈值(例如Logger::INFO)。
公共类方法
new(logdev, shift_age = 0, shift_size = 1048576)
new(logdev, shift_age = 'weekly')
new(logdev, level: :info)
new(logdev, progname: 'progname')
new(logdev, formatter: formatter)
new(logdev, datetime_format: '%Y-%m-%d %H:%M:%S')
Args
logdev
日志设备。这是一个文件名(String)或IO对象(典型地STDOUT
,STDERR
或一个打开的文件)。
shift_age
旧的日志文件数保持,或旋转的频率(daily
,weekly
或monthly
)。默认值是0。
shift_size
以字节为单位的最大日志文件大小(仅适用于shift_age
数字时)。默认为1048576
(1MB)。
level
记录严重性阈值。默认值是Logger::DEBUG。
progname
要包含在日志消息中的程序名称。默认值是零。
formatter
记录格式化程序。默认值是Logger :: Formatter的一个实例。
datetime_format
日期和时间格式。默认值是'%Y-%m-%d%H:%M:%S'。
shift_period_suffix
日志文件后缀格式daily
,weekly
或monthly
旋转。默认值是'%Y%m%d'。
说明
创建一个实例。
# File lib/logger.rb, line 376
def initialize(logdev, shift_age = 0, shift_size = 1048576, level: DEBUG, progname: nil, formatter: nil, datetime_format: nil, shift_period_suffix: '%Y%m%d')
self.level = level
self.progname = progname
@default_formatter = Formatter.new self.datetime_format = datetime_format
self.formatter = formatter
@logdev = nil if logdev
@logdev = LogDevice.new(logdev, :shift_age => shift_age,
:shift_size => shift_size,
:shift_period_suffix => shift_period_suffix)
end
end
公共实例方法<<(msg)显示源转储给日志设备的消息,没有任何格式。 如果不存在日志设备,则返回nil
。
.# File lib/logger.rb, line 478
def <<(msg)
unless @logdev.nil?
@logdev.write(msg)
end
end
Logger#add(severity, message = nil, progname = nil) { ... } Show source
Args
severity
严重性。 常量在Logger命名空间中定义:namespace: DEBUG
, INFO
, WARN
, ERROR
, FATAL
, 或者UNKNOWN
. message
日志消息。 一个字符串或例外。
progname
程序名称字符串。 可以省略。 如果没有给出message
消息和block
块,则作为消息处理。
block
可以省略。 如果message
为nil,则调用以获取消息字符串。返回当给定严重性不够高(对于此特定记录器)时,请不记录消息,并返回true
。
描述
如果给定的严重程度足够高,则记录消息。 这是通用日志记录方法。 用户将更倾向于使用调试,信息,警告,错误和致命。
Message format:
message
可以是任何对象,但必须将其转换为字符串才能记录。通常,如果给定对象不是字符串,则使用inspect
。 一个特例是一个Exception
对象,它将被详细打印,包括消息,类和回溯。 如果需要,请参阅msg2str。
Bugs
- 日志文件未锁定。
- 追加打开不需要锁定文件。
- 如果操作系统支持多个I/O,则记录可能会混合。
# File lib/logger.rb, line 454
def add(severity, message = nil, progname = nil)
severity ||= UNKNOWN
if @logdev.nil? or severity < @level
return true
end
progname ||= @progname
if message.nil?
if block_given?
message = yield
else
message = progname
progname = @progname
end
end
@logdev.write(
format_message(format_severity(severity), Time.now, progname, message))
true
end
Also aliased as: log
close() Show source
关闭日志记录设备。
# File lib/logger.rb, line 567
def close
@logdev.close if @logdev
end
datetime_format() Show source
返回使用的日期格式。请参阅datetime_format =
# File lib/logger.rb, line 299
def datetime_format
@default_formatter.datetime_format
end
datetime_format=(datetime_format) Show source
Set date-time format.
datetime_format
适合传递给的字符串strftime
。
# File lib/logger.rb, line 294
def datetime_format=(datetime_format)
@default_formatter.datetime_format = datetime_format
end
debug(progname = nil, &block) Show source
记录一条DEBUG
消息。
有关更多信息,请参阅info。
# File lib/logger.rb, line 489
def debug(progname = nil, &block)
add(DEBUG, nil, progname, &block)
end
debug?() Show source
返回true
当且仅当目前的严重性级别允许的打印DEBUG
信息。
# File lib/logger.rb, line 322
def debug?; @level <= DEBUG; end
error(progname = nil, &block) Show source
记录ERROR
消息。
有关更多信息,请参阅info。
# File lib/logger.rb, line 541
def error(progname = nil, &block)
add(ERROR, nil, progname, &block)
end
error?() Show source
返回true
当且仅当目前的严重性级别允许的打印ERROR
信息。
# File lib/logger.rb, line 334
def error?; @level <= ERROR; end
fatal(progname = nil, &block) Show source
Log a FATAL
message.
有关更多信息,请参阅 info。
# File lib/logger.rb, line 550
def fatal(progname = nil, &block)
add(FATAL, nil, progname, &block)
end
fatal?() Show source
返回true
当且仅当目前的严重性级别允许的打印FATAL
信息。
# File lib/logger.rb, line 338
def fatal?; @level <= FATAL; end
info(message) Show source
info(progname, &block)
Log an INFO
message.
message
要记录的消息; 不需要是一个字符串。
progname
在块形式中,这是在日志消息中使用的程序名。默认值可以使用progname =进行设置。
block
评估到要记录的消息。除非记录器的级别足以记录消息,否则不会进行评估。这允许您创建可能昂贵的日志消息,这些日志消息仅在记录器配置为显示它们时才会调用。
例子
logger.info("MainApp") { "Received connection from #{ip}" }
# ...
logger.info "Waiting for input from user"
# ...
logger.info { "User typed #{input}" }
你可能会坚持上面的第二种形式,除非你想提供一个程序名(你也可以用progname =来完成)。
返回
See add.
# File lib/logger.rb, line 523
def info(progname = nil, &block)
add(INFO, nil, progname, &block)
end
info?() Show source
返回true
当且仅当目前的严重性级别允许的打印INFO
信息。
# File lib/logger.rb, line 326
def info?; @level <= INFO; end
level=(severity) Show source
设置日志严重性阈值。
severity
日志消息的严重性。
# File lib/logger.rb, line 265
def level=(severity)
if severity.is_a?(Integer)
@level = severity
else
case severity.to_s.downcase
when 'debug'.freeze
@level = DEBUG
when 'info'.freeze
@level = INFO
when 'warn'.freeze
@level = WARN
when 'error'.freeze
@level = ERROR
when 'fatal'.freeze
@level = FATAL
when 'unknown'.freeze
@level = UNKNOWN
else
raise ArgumentError, "invalid log level: #{severity}"
end
end
end
Also aliased as: sev_threshold=
log(severity, message = nil, progname = nil)
Alias for: add
Logger#reopen Show source
Logger#reopen(logdev)
Args
logdev
日志设备。这是一个文件名(String)或IO对象(典型地STDOUT
,STDERR
或一个打开的文件)。如果是的话nil
,重新打开相同的文件名,对IO不做任何事情。默认是nil
。
描述
重新打开日志设备。
# File lib/logger.rb, line 408
def reopen(logdev = nil)
@logdev.reopen(logdev)
self
end
sev_threshold=(severity)
Alias for: level=
unknown(progname = nil, &block) Show source
记录UNKNOWN
消息。无论记录仪的级别是什么,这都将被打印出来。
有关更多信息,请参阅 info。
# File lib/logger.rb, line 560
def unknown(progname = nil, &block)
add(UNKNOWN, nil, progname, &block)
end
warn(progname = nil, &block) Show source
记录一条WARN
消息。
有关更多信息,请参阅info。
# File lib/logger.rb, line 532
def warn(progname = nil, &block)
add(WARN, nil, progname, &block)
end
warn?() Show source
返回true
当且仅当目前的严重性级别允许的打印WARN
信息。
# File lib/logger.rb, line 330
def warn?; @level <= WARN; end
私有实例方法
format_message(severity, datetime, progname, msg) Show source
# File lib/logger.rb, line 580
def format_message(severity, datetime, progname, msg)
(@formatter || @default_formatter).call(severity, datetime, progname, msg)
end
format_severity(severity) Show source
# File lib/logger.rb, line 576
def format_severity(severity)
SEV_LABEL[severity] || 'ANY'
end
本文档系腾讯云开发者社区成员共同维护,如有问题请联系 cloudcommunity@tencent.com