Logging 项目技术文档

1. 安装指南

安装方式

要安装 Logging 库，您可以使用 RubyGems 进行安装。执行以下命令即可：

gem install logging

开发环境设置

如果您计划对 Logging 项目进行开发或测试，您需要安装 Mr Bones 项目以获取默认的 Rake 任务。您可以通过运行以下脚本来设置开发环境：

script/bootstrap

该脚本将安装 Mr Bones 和所需的 Ruby 开发依赖项。安装完成后，您可以运行 rake -T 查看可用的 Rake 任务。

2. 项目的使用说明

基本使用

Logging 是一个灵活的日志库，基于 Java 的 log4j 库设计。它支持分层日志系统、自定义日志级别名称、多个输出目标、自定义格式等功能。

示例 1：基本日志输出

以下示例配置了一个日志记录器，输出格式类似于 Ruby 核心的 Logger 类。只有警告级别及以上的日志消息会被记录。

require 'logging'

logger = Logging.logger(STDOUT)
logger.level = :warn

logger.debug "this debug message will not be output by the logger"
logger.warn "this is your last warning"

示例 2：多输出目标

在这个示例中，创建了一个日志记录器，它将日志消息同时输出到标准输出和文件。只有信息级别及以上的日志消息会被记录。

require 'logging'

logger = Logging.logger['example_logger']
logger.level = :info

logger.add_appenders \
    Logging.appenders.stdout,
    Logging.appenders.file('example.log')

logger.debug "this debug message will not be output by the logger"
logger.info "just some friendly advice"

类级别的日志配置

Logging 库允许程序中的每个类拥有自己的可配置日志记录器。日志级别可以独立于系统中的其他日志记录器进行更改。以下示例展示了如何实现这一点：

require 'logging'

Logging.logger['FirstClass'].level = :warn
Logging.logger['SecondClass'].level = :debug

class FirstClass
  def initialize
    @logger = Logging.logger[self]
  end

  def some_method
    @logger.debug "some method was called on #{self.inspect}"
  end
end

class SecondClass
  def initialize
    @logger = Logging.logger[self]
  end

  def another_method
    @logger.debug "another method was called on #{self.inspect}"
  end
end

3. 项目API使用文档

日志记录器的创建与配置

• Logging.logger(STDOUT)：创建一个日志记录器，输出到标准输出。
• Logging.logger['example_logger']：创建一个命名日志记录器。
• logger.level = :warn：设置日志级别为警告。
• logger.add_appenders(appenders)：添加多个日志输出目标。

日志级别

• :debug：调试级别，最低级别。
• :info：信息级别。
• :warn：警告级别。
• :error：错误级别。
• :fatal：致命错误级别，最高级别。

日志输出目标

• Logging.appenders.stdout：标准输出。
• Logging.appenders.file('example.log')：文件输出。

4. 项目扩展

插件系统

Logging 框架通过 little-plugger 插件系统进行扩展。您可以发布新的 appenders、layouts 或 filters 作为 Ruby gems。安装后，Logging 框架会自动检测这些插件并使其可用。

创建插件的步骤

1. 创建一个新的 Ruby gem：logging-<name>。
2. 包含一个插件文件：lib/logging/plugins/<name>.rb。
3. 定义插件初始化方法：Logging::Plugins::<Name>.initialize_<name>。

示例插件

logging-email 插件是一个很好的示例。它包含一个 lib/logging/plugins/email.rb 文件，该文件声明了一个 Logging::Plugins::Email.initialize_email 方法，在插件加载时调用。

5. 许可证

Logging 项目采用 MIT 许可证，详细内容请参阅 LICENSE 文件。