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

最后更新于：2017-12-18