mellivora/logger-factory

Logger factory component of mellivora framework

v1.1.2 2019-07-24 08:58 UTC

This package is auto-updated.

Last update: 2024-03-24 19:08:57 UTC


README

该库基于 monolog 进行开发,针对 monolog 进行了一系列的扩展,及配置增强功能。

1. 安装

composer require mellivora/logger-factory

2. 使用

根据配置文件实例化

$factory = Mellivora\Logger\LoggerFactory::build(require 'config/logger.php');

php/yaml/json/ini/xml 格式通过 buildWith() 方法加载配置,需要 hassankhan/config 库的支持,其中 yaml 格式需要 symfony/yaml 库的支持

$factory = Mellivora\Logger\LoggerFactory::buildWith('config/logger.yaml');

创建一个已定义的 logger

$factory->get('cli');
// or
$factory['cli'];

根据 default 获取一个未定义的 logger

$factory->get('foo');
// or
$factory['foo'];

复制一个 logger

$factory->get('foo')->withName('bar');

根据 handlers 配置,创建一个 logger

$factory->make('bar', ['cli', 'file']);

也可以把自己定义的 logger 添加到 factory 中

$factory->add('orders', $logger);
$factory->get('orders')->withName('order_create'); // copy from `orders`

并以自定义的 logger 做为默认 logger

$factory->setDefault('orders');

3. 配置

Logger-Factory 支持灵活的配置方式,同时在引入 hassankhan/config 库后,可以支持 yaml/json/ini/xml 等格式的配置文件,具体请参考配置目录文件

推荐安装 symfony/yaml 库后使用,因为 yaml 格式使得配置文件看起来更清晰可读。

3.1 配置文件说明

关于 formatte processor handler 的相关信息,请查看monolog的帮助说明

配置方法

配置文件中,通过 class 指定类的全名,params 指定参数列表。 参考代码内容

3.1.1 formatters

用于最终输出日志消息的格式,通过对应的命名及参数设置,可以提供给后面的 handlers 使用。

# formatters - 用于最终输出日志消息的格式
formatters:

  # 简单消息输出
  simple:
    class: Monolog\Formatter\LineFormatter
    params:
      format: "[%datetime%][%level_name%] %message% %context%\n"

  # 输出消息详情
  venbose:
    class: Monolog\Formatter\LineFormatter
    params:
      format: "[%datetime%][%channel%][%level_name%] %message% %context% %extra%\n"

  # JSON 格式输出,便于 ELK 收集
  json:
    class: Monolog\Formatter\JsonFormatter

3.1.2 processors

通过加载注册的 processor 将会附加在消息的 extra 字段中。

Logger-Factory 中,增加了下面几种 processor 来增强日志的附属信息:

  • CostTimeProcessor - 用于获取时间成本消耗,会记录上次写日志到当前写日志消耗的时间
  • ProfilerProcessor - 可获取时间成本消耗、内存消耗数据
  • ScriptProcessor - 可用于 cli 模式下,获取脚本命令的完整信息
  • WebProcessor - 可用于 http 请求下,获取 web 的部分 header 信息
# processors - 注册的 processor 将会附加在消息的 extra 字段中
processors:
  # 用于日志输出所在 的 file, line, class, method, ...
  intro:
    class: Monolog\Processor\IntrospectionProcessor
    params:
      level: ERROR
      skipStackFramesCount: 2

  # 用于捕获 http web 请求头信息
  web:
    class: Mellivora\Logger\Processor\WebProcessor
    params:
      level: ERROR

  # 用于捕获脚本运行信息
  script:
    class: Mellivora\Logger\Processor\ScriptProcessor
    params:
      level: ERROR

  # 用于性能分析
  profiler:
    class: Mellivora\Logger\Processor\ProfilerProcessor
    params:
      level: DEBUG

3.1.3 handlers

通过拼装 formatter/processor,用于日志输出方式的设定。

Logger-Factory 中,增加了下面几种 handler 来进行日志存储:

  • NamedRotatingFileHandler - 支持日志自动分片、缓冲写入、根据 channel 调整文件名的功能,支持以下参数设定:
    • filename - 日志文件名,可使用 %channel% 来动态生成文件名
    • maxBytes - 单个日志文件最大尺寸,默认值 100000000 (100mb),0为不限制
    • backupCount - 保留的日志备份文件数量,默认值 10,0为不保留备份
    • bufferSize - 缓冲区日志数大小,默认值 0,不开启
    • dateFormat - 备份日志文件的日期格式,默认 Y-m-d
    • level - 日志级别过滤,默认 debug 级别
    • bubble - 设置为 false 日志将被过滤,默认 true
    • filePermission - 文件权限,默认 0644
    • useLocking - 是否对日志文件加锁,默认 false
  • SmtpHandler - 通过加载 swiftmailer,来支持方便快捷的邮件发送配置,支持以下参数设定:
    • sender - 发件人,支持两种格式 john@mailhost.com John <john@mailhost.com>
    • receivers - 收件人,数组或字符类型,格式同发件人
    • subject - 邮件主题
    • certificates - 服务器认证信息,包含 [host,port,username,password]
    • maxRecords - 最大记录数,达到该数量后将立即发送邮件,默认为 10
    • level
    • bubble
# handlers - 通过拼装 formatter/processor,用于日志输出方式的设定
handlers:

  # 文件输出,使用 JSON 格式,方便 ELK 收集
  file:
    class: Mellivora\Logger\Handler\NamedRotatingFileHandler
    params:
      filename: "logs/%channel%.log"
      maxBytes: 100000000 # 100Mb,文件最大尺寸
      backupCount: 10 # 文件保留数量
      bufferSize: 10 # 缓冲区大小(日志数量)
      level: INFO
    formatter: json
    processors: [intro, web, script, profiler]

  # 命令行模式,输出简单日志内容
  cli:
    class: Monolog\Handler\StreamHandler
    params:
      stream: php://stdout
      level: DEBUG
    formatter: simple

  # 邮件预警,仅报告致命错误 CRITICAL
  mail:
    class: Mellivora\Logger\Handler\SmtpHandler
    params:
      sender: logger-factory <sender@mailhost.com>
      receivers:
        - receiver <receiver@mailhost.com>
      subject: "[ERROR] FROM Logger-Factory"
      certificates:
        host: smtp.mailhost.com
        port: 25
        username: sender@mailhost.com
        password: sender-passwd
      maxRecords: 10
      level: CRITICAL
    formatter: venbose
    processors: [intro, web, script, profiler]

3.1.4 loggers

当声明的 logger 不在以下列表中时,默认为 default。参考默认配置:

# loggers -  当声明的 logger 不在以下列表中时,默认为 default
loggers:

  # 默认日志
  default: [file, mail]

  # 命令行模式
  cli: [cli, file, mail]

  # 异常处理
  exception: [file, mail]

4. 过滤器的使用

Mellivora\Logger\Logger 新增了 filter 过滤器的支持。

对日志消息进行替换

$logger->addFilter(function($level, &$message, &$context) {
    if (isset($context['password'])) {
        $context['password'] = '******';
    }

    $message = preg_replace('/password=[^&]+/', 'password=******', $message);

    return true;
});

对日志消息进行过滤

$logger->addFilter(function($level, $message, $context) {
    return !isset($context['password']);
});

自定义过滤器类

class PasswordFilter
{
    public function __invoke($level, $message, $context)
    {
        // ...
    }
}
$logger->addFilter(new PasswordFilter);

5. 日志路径支持

Mellivora\Logger\LoggerFactory 提供了关于项目根目录设置的方法,用于来协助日志文件目录定位。

Mellivora\Logger\LoggerFactory::setRootPath('/your/application');

Mellivora\Logger\Handler\NamedRotatingFileHandler 中,采用了如下方法来获取日志目录

$filename = LoggerFactory::getRootPath() . '/' . $filename;

你也可以利用 LoggerFactory::getRootPath() 来定义自己的日志 handler,协助方便的指定日志路径。

License

The MIT License (MIT). Please see License File for more information.