class Logger

Logger 类提供了一个简单但功能强大的日志实用程序，你可以使用它为你的程序创建一个或多个事件日志。每个这样的日志都包含一个按时间顺序排列的条目序列，记录了程序的活动。

关于示例¶ ↑

此页面上的所有示例都假设已经 require 了 Logger

require 'logger'

概要¶ ↑

使用 Logger.new 创建日志

# Single log file.
logger = Logger.new('t.log')
# Size-based rotated logging: 3 10-megabyte files.
logger = Logger.new('t.log', 3, 10485760)
# Period-based rotated logging: daily (also allowed: 'weekly', 'monthly').
logger = Logger.new('t.log', 'daily')
# Log to an IO stream.
logger = Logger.new($stdout)

使用 Logger#add 添加条目（级别，消息）

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')

使用 Logger#close 关闭日志

logger.close

条目¶ ↑

你可以使用方法 Logger#add 添加条目

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')

这些简写方法也添加条目

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')

当你调用这些方法中的任何一个时，条目可能会或可能不会写入日志，具体取决于条目的严重程度和日志级别；请参阅日志级别

一个条目始终具有

• 严重程度（add 的必需参数）。

• 自动创建的时间戳。

并且还可能具有

• 消息。

• 程序名称。

示例

logger = Logger.new($stdout)
logger.add(Logger::INFO, 'My message.', 'mung')
# => I, [2022-05-07T17:21:46.536234 #20536]  INFO -- mung: My message.

条目的默认格式是

"%s, [%s #%d] %5s -- %s: %s\n"

其中要格式化的值是

• 严重程度（一个字母）。

• 时间戳。

• 进程 ID。

• 严重程度（单词）。

• 程序名称。

• 消息。

你可以使用不同的条目格式，方法是

• 设置自定义格式 proc（影响后续条目）；请参阅 formatter=。

• 使用块调用上述任何方法（仅影响一个条目）。这样做有两个好处

  • 上下文：该块可以评估整个程序上下文并创建依赖于上下文的消息。

  • 性能：除非日志级别允许实际写入条目，否则不会评估该块

    logger.error { my_slow_message_generator }
    

    将此与字符串形式进行对比，字符串形式始终会进行评估，无论日志级别如何

    logger.error("#{my_slow_message_generator}")
    

严重程度¶ ↑

日志条目的严重程度有两个影响

• 确定是否选择将条目包含在日志中；请参阅日志级别。

• 向任何日志读取器（无论是人还是程序）指示条目的相对重要性。

时间戳¶ ↑

日志条目的时间戳是在创建条目时自动生成的。

记录的时间戳由方法 Time#strftime 使用此格式字符串格式化

'%Y-%m-%dT%H:%M:%S.%6N'

示例

logger = Logger.new($stdout)
logger.add(Logger::INFO)
# => I, [2022-05-07T17:04:32.318331 #20536]  INFO -- : nil

你可以使用方法 datetime_format= 设置不同的格式。

消息¶ ↑

消息是条目方法的可选参数

logger = Logger.new($stdout)
logger.add(Logger::INFO, 'My message')
# => I, [2022-05-07T18:15:37.647581 #20536]  INFO -- : My message

对于默认的条目格式化程序 Logger::Formatter，消息对象可以是

• 字符串：按原样使用。

• 异常：使用 message.message。

• 任何其他内容：使用 message.inspect。

注意：Logger::Formatter 不会转义或清理传递给它的消息。开发人员应注意，恶意数据（用户输入）可能位于消息中，并且应显式转义不受信任的数据。

你可以使用自定义格式化程序来转义消息数据；请参阅 formatter= 的示例。

程序名称¶ ↑

程序名称是条目方法的可选参数

logger = Logger.new($stdout)
logger.add(Logger::INFO, 'My message', 'mung')
# => I, [2022-05-07T18:17:38.084716 #20536]  INFO -- mung: My message

可以在调用 Logger.new 时，通过可选关键字参数 progname 设置新日志记录器的默认程序名称

logger = Logger.new('t.log', progname: 'mung')

可以通过调用方法 progname= 设置现有日志记录器的默认程序名称

logger.progname = 'mung'

可以使用方法 progname 检索当前程序名称

logger.progname # => "mung"

日志级别¶ ↑

日志级别设置基于条目的严重程度确定是否实际将条目写入日志。

以下是定义的严重程度（从最不严重到最严重）

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

默认的初始级别设置为 Logger::DEBUG，即最低级别，这意味着将写入所有条目，无论严重程度如何

logger = Logger.new($stdout)
logger.level # => 0
logger.add(0, "My message")
# => D, [2022-05-11T15:10:59.773668 #20536] DEBUG -- : My message

你可以在新的日志记录器中使用关键字参数 level 以及适当的值指定不同的设置

logger = Logger.new($stdout, level: Logger::ERROR)
logger = Logger.new($stdout, level: 'error')
logger = Logger.new($stdout, level: :error)
logger.level # => 3

使用此级别，将写入严重程度为 Logger::ERROR 及更高的条目，而不会写入严重程度较低的条目

logger = Logger.new($stdout, level: Logger::ERROR)
logger.add(3)
# => E, [2022-05-11T15:17:20.933362 #20536] ERROR -- : nil
logger.add(2) # Silent.

可以使用方法 level= 设置现有日志记录器的日志级别

logger.level = Logger::ERROR

这些简写方法也设置级别

logger.debug! # => 0
logger.info!  # => 1
logger.warn!  # => 2
logger.error! # => 3
logger.fatal! # => 4

可以使用方法 level 检索日志级别。

logger.level = Logger::ERROR
logger.level # => 3

这些方法返回是否要写入给定的级别

logger.level = Logger::ERROR
logger.debug? # => false
logger.info?  # => false
logger.warn?  # => false
logger.error? # => true
logger.fatal? # => true

日志文件轮转¶ ↑

默认情况下，日志文件是一个无限增长的单个文件（直到显式关闭）；没有文件轮转。

为了使日志文件保持在可管理的大小，你可以使用日志 文件 轮转，它使用多个日志文件

• 每个日志文件都有不重叠时间间隔的条目。

• 只有最新的日志文件是打开和活动的；其他文件是关闭和非活动的。

基于大小的轮转¶ ↑

对于基于大小的日志文件轮转，请使用以下参数调用 Logger.new

• 参数 logdev 作为文件路径。

• 参数 shift_age 为正整数：轮转中要使用的日志文件数。

• 参数 shift_size 为正整数：每个日志文件的最大大小（以字节为单位）；默认为 1048576（1 兆字节）。

示例

logger = Logger.new('t.log', 3)           # Three 1-megabyte files.
logger = Logger.new('t.log', 5, 10485760) # Five 10-megabyte files.

对于这些示例，假设

logger = Logger.new('t.log', 3)

日志记录在新日志文件 t.log 中开始；当新条目导致其大小超过 shift_size 时，该日志文件将“满”并准备好进行轮转。

t.log 首次满时

• t.log 被关闭并重命名为 t.log.0。

• 将打开一个新文件 t.log。

t.log 第二次满时

• +t.log.0 被重命名为 t.log.1。

• t.log 被关闭并重命名为 t.log.0。

• 将打开一个新文件 t.log。

每次后续 t.log 文件满时，都会轮转日志文件

• t.log.1 被删除。

• +t.log.0 被重命名为 t.log.1。

• t.log 被关闭并重命名为 t.log.0。

• 将打开一个新文件 t.log。

定期轮转¶ ↑

对于定期轮转，请使用以下参数调用 Logger.new

• 参数 logdev 作为文件路径。

• 参数 shift_age 作为字符串周期指示符。

示例

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.

示例

logger = Logger.new('t.log', 'daily')

当给定的周期过期时

• 基本日志文件 t.log 被关闭，并使用基于日期的后缀（例如 t.log.20220509）重命名。

• 将打开一个新的日志文件 t.log。

• 不删除任何内容。

后缀的默认格式为 '%Y%m%d'，这将生成类似于上面的后缀。你可以使用创建时选项 shift_period_suffix 设置不同的格式；请参阅 Time#strftime 的详细信息和建议。