SeasLog PHP 日志扩展

README

SeasLog
======
[![Build Status](https://travis-ci.org/SeasX/SeasLog.svg?branch=master)](https://travis-ci.org/SeasX/SeasLog)
[![Build status](https://ci.appveyor.com/api/projects/status/xkf8y7msk7kskon2?svg=true)](https://ci.appveyor.com/project/Neeke/seaslog)

An effective,fast,stable log extension for PHP

@author Chitao.Gao [neeke@php.net]

@交流群 312910117

[PHP手册](http://php.net/SeasLog)

[English Document](https://github.com/SeasX/SeasLog/blob/master/README.md)

[日志规范](https://github.com/SeasX/SeasLog/blob/master/Specification/README_zh.md)

[日志收集](https://github.com/SeasX/SeasLog/blob/master/Specification/SeasLog_Rsyslog_ELK_zh.md)

> ---
- **[简介](#简介)**
    - **[为什么使用SeasLog](#为什么使用seaslog)**
    - **[目前提供了什么](#目前提供了什么)**
    - **[目标是怎样的](#目标是怎样的)**
- **[安装](#安装)**
    - **[编译安装 SeasLog](#编译安装-seaslog)**
    - **[seaslog.ini的配置](#seaslogini的配置)**
    - **[自定义日志模板](#自定义日志模板)**
        - [日志模板说明](#日志模板说明)
        - [预设变量表](#预设变量表)
- **[使用](#使用)**
    - **[常量与函数](#常量与函数)**
        - [常量列表](#常量列表)
        - [函数列表](#函数列表)
    - **[PHP Re 结果](#php-re-结果)**
    - **[SeasLog Logger的使用](#seaslog-logger的使用)**
        - [获取与设置basePath](#获取与设置basepath)
        - [设置logger与获取lastLogger](#设置logger与获取lastlogger)
        - [快速写入log](#速写入log)
        - [使用TCP或UDP发送时的数据格式](#使用tcp或udp发送时的数据格式)
        - [手动清除LoggerStream缓存](#手动清除loggerstream缓存)
    - **[SeasLog Analyzer的使用](#seaslog-analyzer的使用)**
        - [快速统计某类型log的count值](#快速统计某类型log的count值)
        - [获取某类型log列表](#获取某类型log列表)
    - **[使用SeasLog进行健康预警](#使用seaslog进行健康预警)**
        - [预警的配置](#预警的配置)
        - [crontab配置](#crontab配置)
    - **[目前已知使用SeasLog的企业](#目前已知使用SeasLog的企业)**
        - [企业名单](#企业名单)
        - [接受捐赠](#接受捐赠)


> ---

## 简介
### 为什么使用SeasLog
log日志，通常是系统或软件、应用的运行记录。通过log的分析，可以方便用户了解系统或软件、应用的运行情况；如果你的应用log足够丰富，也可以分析以往用户的操作行为、类型喜好、地域分布或其他更多信息；如果一个应用的log同时也分了多个级别，那么可以很轻易地分析得到该应用的健康状况，及时发现问题并快速定位、解决问题，补救损失。

php内置error_log、syslog函数功能强大且性能极好，但由于各种缺陷(error_log无错误级别、无固定格式，syslog不分模块、与系统日志混合)，灵活度降低了很多，不能满足应用需求。

好消息是，有不少第三方的log类库弥补了上述缺陷，如log4php、plog、Analog等(当然也有很多应用在项目中自己开发的log类)。其中以[log4php](http://logging.apache.org/log4php/)最为著名，设计精良、格式完美、文档完善、功能强大。推荐。

不过log4php在性能方面表现非常差,下图是SeasLog与log4php的ab并发性能测试( 测试环境:Ubuntu12.04单机,CPU I3,内存 16G,硬盘 SATA 7200):
![SeasLogVSlog4php](https://raw.githubusercontent.com/SeasX/SeasLog/master/tests/SeasLogVSlog4php.png)


那么有没有一种log类库满足以下需求呢：
* 分模块、分级别
* 配置简单(最好是勿须配置)
* 日志格式清晰易读
* 应用简单、性能很棒

`SeasLog` 正是应此需求而生。

### 目前提供了什么
* 在PHP项目中便捷、规范地记录log
* 可配置的默认log目录与模块
* 指定log目录与获取当前配置
* 初步的分析预警框架
* 高效的日志缓冲、便捷的缓冲debug
* 遵循 [PSR-3](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md) 日志接口规范
* 自动记录错误信息
* 自动记录异常信息
* 连接TCP端口，以RFC5424格式发送日志
* 连接UDP端口，以RFC5424格式发送日志
* 支持RequestId区分请求
* 支持日志模板自定义

### 目标是怎样的
* 便捷、规范的log记录
* 高效的海量log分析
* 可配置、多途径的log预警

## 安装

### 编译安装 SeasLog
```sh
$ /path/to/phpize
$ ./configure --with-php-config=/path/to/php-config
$ make && make install
```

### PECL安装SeasLog
```sh
$ pecl install seaslog
```

### Windows环境中使用SeasLog
到PECL/SeasLog主页找到对应的dll进行安装 [PECL/SeasLog Windows Dll](http://pecl.php.net/package/SeasLog/1.8.4/windows)

### seaslog.ini的配置
```conf
[SeasLog]
;configuration for php SeasLog module
extension = seaslog.so

;默认log根目录
seaslog.default_basepath = "/var/log/www"

;默认log文件前缀 如 "app-" 默认空字符串
seaslog.default_file_prefix = ""

;默认log文件日期分隔符 如 "-" 默认空字符串
seaslog.default_file_datetime_separator=""

;默认logger目录
seaslog.default_logger = "default"

;日期格式配置 默认"Y-m-d H:i:s"
seaslog.default_datetime_format = "Y-m-d H:i:s"

;日志格式模板 默认"%T | %L | %P | %Q | %t | %M"
seaslog.default_template = "%T | %L | %P | %Q | %t | %M"

;是否以目录区分Logger 1是(默认) 0否
seaslog.disting_folder = 1

;是否以type分文件 1是 0否(默认)
seaslog.disting_type = 0

;是否每小时划分一个文件 1是 0否(默认)
seaslog.disting_by_hour = 0

;是否启用buffer 1是 0否(默认)
seaslog.use_buffer = 0

;buffer中缓冲数量 默认0(不使用buffer_size)
seaslog.buffer_size = 100

;cli运行时关闭buffer
;1是 0否(默认)
seaslog.buffer_disabled_in_cli = 0

;记录日志级别，数字越大，根据级别记的日志越多。
;0-EMERGENCY 1-ALERT 2-CRITICAL 3-ERROR 4-WARNING 5-NOTICE 6-INFO 7-DEBUG 8-ALL
;默认8(所有日志)
;
;   注意, 该配置项自1.7.0版本开始有变动。
;   在1.7.0版本之前, 该值数字越小，根据级别记的日志越多: 
;   0-all 1-debug 2-info 3-notice 4-warning 5-error 6-critical 7-alert 8-emergency
;   1.7.0 之前的版本，该值默认为0(所有日志);
seaslog.level = 8

;日志函数调用回溯层级
;影响预定义变量 %F 中的行数
;默认0
seaslog.recall_depth = 0

;自动记录notice 默认0(关闭)
seaslog.trace_notice = 0

;自动记录warning 默认0(关闭)
seaslog.trace_warning = 0

;自动记录错误 默认1(开启)
seaslog.trace_error = 1

;自动记录异常信息 默认0(关闭)
seaslog.trace_exception = 0

;日志存储介质 1File 2TCP 3UDP (默认为1)
seaslog.appender = 1

;写入重试次数
;默认0(不重试)
seaslog.appender_retry = 0

;接收ip 默认127.0.0.1 (当使用TCP或UDP时必填)
seaslog.remote_host = "127.0.0.1"

;接收端口 默认514 (当使用TCP或UDP时必填)
seaslog.remote_port = 514

;接收端口的超时时间 默认1秒
seaslog.remote_timeout = 1

;过滤日志中的回车和换行符 (默认为0)
seaslog.trim_wrap = 0

;是否开启抛出SeasLog自身异常  1开启(默认) 0关闭
seaslog.throw_exception = 1

;是否开启忽略SeasLog自身warning  1开启(默认) 0关闭
seaslog.ignore_warning = 1

;是否开启性能追踪 1开启 0关闭(默认)
seaslog.trace_performance = 0

;性能追踪时的千分比采样率
;默认10，即百分之一
seaslog.trace_performance_sample_rate = 10

;性能追踪时的开始层级 默认从第1层开始
seaslog.trace_performance_start_depth = 1

;性能追踪时深度层级 默认5层
seaslog.trace_performance_max_depth = 5

;性能追踪时每层的函数最大数 按wall_time降序排列top 默认top5
seaslog.trace_performance_max_functions_per_depth = 5

;性能追踪时当前请求执行时间的记录阈值 只有当请求执行时间大于该值时，才记录性能日志 默认1000ms
seaslog.trace_performance_min_wall_time = 1000

;性能追踪时每个方法执行时间的记录阈值 只有当方法执行时间大于该值时，才参与计算 默认10ms
seaslog.trace_performance_min_function_wall_time = 10
```
> `seaslog.disting_folder = 1` 开启以目录分文件，即logger以目录区分。当关闭时，logger以下划线拼接时间, 如default_20180211.log。

> `seaslog.disting_type = 1` 开启以type分文件，即log文件区分info\warn\erro

> `seaslog.disting_by_hour = 1` 开启每小时划分一个文件

> `seaslog.use_buffer = 1` 开启buffer。默认关闭。当开启此项时，日志预存于内存，当请求结束时(或异常退出时)一次写入文件。

> `seaslog.buffer_size = 100` 设置缓冲数量为100. 默认为0,即无缓冲数量限制.当buffer_size大于0时,缓冲量达到该值则写一次文件.

> `seaslog.buffer_disabled_in_cli = 1` 开启CLI运行时禁用缓存。默认关闭。当开启此项时，CLI运行时将忽略seaslog.use_buffer设定，日志写入文件。

> `seaslog.level = 8` 记录的日志级别.默认为8,即所有日志均记录。