update readme & default configurations

zhouyl · Sep 19, 2018 · 20b1ab4 · 20b1ab4
1 parent affa9c2
commit 20b1ab4
Show file tree

Hide file tree

Showing 4 changed files with 99 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@ composer require mellivora/logger-factory
 $factory = Mellivora\Logger\LoggerFactory::build(require 'config/logger.php');
 ```
 
-`yaml/json/ini` 格式通过 `buildWith` 方法加载配置，需要 `hassankhan/config` 库的支持，其中 `yaml` 格式需要 `symfony/yaml` 库的支持
+`php`/`yaml`/`json`/`ini`/`xml` 格式通过 `buildWith()` 方法加载配置，需要 `hassankhan/config` 库的支持，其中 `yaml` 格式需要 `symfony/yaml` 库的支持
 
 ```php
 $factory = Mellivora\Logger\LoggerFactory::buildWith('config/logger.yaml');
@@ -38,6 +38,12 @@ $factory->get('foo');
 $factory['foo'];
 ```
 
+复制一个 logger
+
+```php
+$factory->get('foo')->withName('bar');
+```
+
 根据 handlers 配置，创建一个 logger
 
 ```php
@@ -47,13 +53,14 @@ $factory->make('bar', ['cli', 'file']);
 也可以把自己定义的 logger 添加到 factory 中
 
 ```php
-$factory->add('foo', new Monolog\Logger('mylogger'));
+$factory->add('orders', $logger);
+$factory->get('orders')->withName('order_create'); // copy from `orders`
 ```
 
 并以自定义的 logger 做为默认 logger
 
 ```php
-$factory->setDefault('foo');
+$factory->setDefault('orders');
 ```
 
 ## 3. 配置
@@ -74,6 +81,27 @@ $factory->setDefault('foo');
 
 用于最终输出日志消息的格式，通过对应的命名及参数设置，可以提供给后面的 `handlers` 使用。
 
+```yaml
+# 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 字段中。
@@ -85,14 +113,33 @@ $factory->setDefault('foo');
 -  [ScriptProcessor](src/Processor/ScriptProcessor.php) - 可用于 cli 模式下，获取脚本命令的完整信息
 -  [WebProcessor](src/Processor/WebProcessor.php) - 可用于 http 请求下，获取 web 的部分 header 信息
 
-例如:
-
 ```yaml
+# 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: ERROR # 限定 >= ERROR 级别的日志才输出
+      level: DEBUG
 ```
 
 #### 3.1.3 handlers
@@ -120,10 +167,11 @@ processors:
     - `level`
     - `bubble`
 
-例如:
-
 ```yaml
+# handlers - 通过拼装 formatter/processor，用于日志输出方式的设定
 handlers:
+
+  # 文件输出，使用 JSON 格式，方便 ELK 收集
   file:
     class: Mellivora\Logger\Handler\NamedRotatingFileHandler
     params:
@@ -133,14 +181,41 @@ handlers:
       bufferSize: 10 # 缓冲区大小(日志数量)
       level: INFO
     formatter: json
-    processors: [intro, web, script, profiler] # 这里使用各种 processor 的命名
+    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 <[email protected]>
+      receivers:
+        - receiver <[email protected]>
+      subject: "[ERROR] FROM Logger-Factory"
+      certificates:
+        host: smtp.mailhost.com
+        port: 25
+        username: [email protected]
+        password: sender-passwd
+      maxRecords: 10
+      level: CRITICAL
+    formatter: venbose
+    processors: [intro, web, script, profiler]
 ```
 
 #### 3.1.4 loggers
 
 当声明的 logger 不在以下列表中时，默认为 default。参考默认配置:
 
 ```yaml
+# loggers -  当声明的 logger 不在以下列表中时，默认为 default
 loggers:
 
   # 默认日志
@@ -150,22 +225,14 @@ loggers:
   cli: [cli, file, mail]
 
   # 异常处理
-  exception: [cli, file, mail]
+  exception: [file, mail]
 ```
 
 ## 4. 过滤器的使用
 
-`Mellivora\Logger\Logger` 新增了 `filter` 过滤器的支持
-
-```php
-$logger = new Mellivora\Logger\Logger('mail-warning');
-
-// or
-
-$logger = $factory->make('mail-warning', 'mail');
-```
+`Mellivora\Logger\Logger` 新增了 `filter` 过滤器的支持。
 
-对日志中的消息进行替换
+对日志消息进行替换
 
 ```php
 $logger->addFilter(function($level, &$message, &$context) {
@@ -197,15 +264,15 @@ class PasswordFilter
         // ...
     }
 }
+$logger->addFilter(new PasswordFilter);
 ```
 
 ## 5. 日志路径支持
 
 `Mellivora\Logger\LoggerFactory` 提供了关于项目根目录设置的方法，用于来协助日志文件目录定位。
 
 ```php
-use Mellivora\Logger\LoggerFactory;
-LoggerFactory::setRootPath('/your/application');
+Mellivora\Logger\LoggerFactory::setRootPath('/your/application');
 ```
 
 在 `Mellivora\Logger\Handler\NamedRotatingFileHandler` 中，采用了如下方法来获取日志目录

diff --git a/config/logger.json b/config/logger.json
@@ -55,9 +55,6 @@
             },
             "formatter": "json",
             "processors": [
-                "intro",
-                "web",
-                "script",
                 "profiler"
             ]
         },
@@ -67,20 +64,14 @@
                 "stream": "php://stdout",
                 "level": "DEBUG"
             },
-            "formatter": "simple",
-            "processors": [
-                "intro",
-                "web",
-                "script",
-                "profiler"
-            ]
+            "formatter": "simple"
         },
         "mail": {
             "class": "Mellivora\\Logger\\Handler\\SmtpHandler",
             "params": {
                 "sender": "logger-factory <[email protected]>",
                 "receivers": [
-                    "zhouyl <81438567@qq.com>"
+                    "receiver <receiver@mailhost.com>"
                 ],
                 "subject": "[ERROR] FROM Logger-Factory",
                 "certificates": {
@@ -103,7 +94,6 @@
     },
     "loggers": {
         "default": [
-            "cli",
             "file",
             "mail"
         ],
@@ -113,7 +103,6 @@
             "mail"
         ],
         "exception": [
-            "cli",
             "file",
             "mail"
         ]

diff --git a/config/logger.php b/config/logger.php
@@ -61,7 +61,7 @@
             'level'       => 'INFO',
         ],
         'formatter'  => 'json',
-        'processors' => ['intro', 'web', 'script', 'profiler'],
+        'processors' => ['profiler'],
     ],
     'cli' => [
         'class'  => 'Monolog\Handler\StreamHandler',
@@ -76,7 +76,7 @@
         'params' => [
             'sender'     => 'logger-factory <[email protected]>',
             'receivers'  => [
-                'zhouyl <81438567@qq.com>',
+                'receiver <receiver@mailhost.com>',
             ],
             'subject'      => '[ERROR] FROM Logger-Factory',
             'certificates' => [
@@ -95,9 +95,9 @@
 
 // loggers -  当声明的 logger 不在以下列表中时，默认为 default
 $loggers = [
-    'default'   => ['cli', 'file', 'mail'],
+    'default'   => ['file', 'mail'],
     'cli'       => ['cli', 'file', 'mail'],
-    'exception' => ['cli', 'file', 'mail'],
+    'exception' => ['file', 'mail'],
 ];
 
 return [

diff --git a/config/logger.yaml b/config/logger.yaml
@@ -57,7 +57,7 @@ handlers:
       bufferSize: 10 # 缓冲区大小(日志数量)
       level: INFO
     formatter: json
-    processors: [intro, web, script, profiler]
+    processors: [profiler]
 
   # 命令行模式，输出简单日志内容
   cli:
@@ -66,15 +66,14 @@ handlers:
       stream: php://stdout
       level: DEBUG
     formatter: simple
-    processors: [intro, web, script, profiler]
 
   # 邮件预警，仅报告致命错误 CRITICAL
   mail:
     class: Mellivora\Logger\Handler\SmtpHandler
     params:
       sender: logger-factory <[email protected]>
       receivers:
-        - zhouyl <81438567@qq.com>
+        - receiver <receiver@mailhost.com>
       subject: "[ERROR] FROM Logger-Factory"
       certificates:
         host: smtp.mailhost.com
@@ -90,10 +89,10 @@ handlers:
 loggers:
 
   # 默认日志
-  default: [cli, file, mail]
+  default: [file, mail]
 
   # 命令行模式
   cli: [cli, file, mail]
 
   # 异常处理
-  exception: [cli, file, mail]
+  exception: [file, mail]