PHP日志接口規(guī)范

關(guān)于日志系統(tǒng)，PHP規(guī)范給出了相當(dāng)好的說(shuō)明和定義，請(qǐng)見(jiàn)： Logger Interface

1.17.1 簡(jiǎn)化版

但在用過(guò)這么多開(kāi)源框架進(jìn)行各種項(xiàng)目開(kāi)發(fā)，以及內(nèi)部框架的開(kāi)發(fā)后，發(fā)現(xiàn)實(shí)際上日志的分類并沒(méi)有使用得這么豐富，而通常只是頻繁地幾類。因此，為了減少不必要的復(fù)雜性，這里特地精簡(jiǎn)為三種，只有：

• error 系統(tǒng)異常類
• info 業(yè)務(wù)紀(jì)錄類
• debug 開(kāi)發(fā)調(diào)試類

現(xiàn)分說(shuō)如下。

(1)error 系統(tǒng)異常類

此類是后臺(tái)開(kāi)發(fā)同學(xué)認(rèn)為 不應(yīng)該發(fā)生卻發(fā)生的事情 ，即我們通常所說(shuō)的系統(tǒng)異常。
如：調(diào)用app store支付的接口失敗了，我們需要紀(jì)錄一下當(dāng)時(shí)的場(chǎng)景，以便復(fù)查和給用戶補(bǔ)嘗其損失。
又如：寫入一條紀(jì)錄到數(shù)據(jù)紀(jì)錄，但失敗了，我們需要紀(jì)錄一下，以便排查。

用法很簡(jiǎn)單，如：

//只有描述
DI()->logger->error('fail to insert DB');

//描述 + 簡(jiǎn)單的信息
DI()->logger->error('fail to insert DB', 'try to register user dogstar');

//描述 + 當(dāng)時(shí)的上下文數(shù)據(jù)
$data = array('name' => 'dogstar', 'password' => '123456');
DI()->logger->error('fail to insert DB', $data);

上面三條紀(jì)錄，效果類如：

dogstar@ubuntu:dev.phalapi.com$ tailf ./Runtime/log/201502/20150207.log 
2015-02-07 20:37:55|ERROR|fail to insert DB
2015-02-07 20:37:55|ERROR|fail to insert DB|try to register user dogstar
2015-02-07 20:37:55|ERROR|fail to insert DB|{"name":"dogstar","password":"123456"}

截圖效果：

(2)info 業(yè)務(wù)紀(jì)錄類

此類通常為業(yè)務(wù)需要進(jìn)行必要的操作紀(jì)錄，以便發(fā)生系統(tǒng)問(wèn)題后的回滾處理、問(wèn)題排查以及數(shù)據(jù)統(tǒng)計(jì)。
如在有緩存的情況下，可能數(shù)據(jù)沒(méi)及時(shí)寫入數(shù)據(jù)庫(kù)而導(dǎo)致數(shù)據(jù)丟失或者回檔，這里可以通過(guò)日志簡(jiǎn)單查看是否可以恢復(fù)。以及說(shuō)明一下操作發(fā)生的背景或原由，如通常游戲中用戶的經(jīng)驗(yàn)值添加：

//假設(shè)：10 + 2 = 12
DI()->logger->info('add user exp', array('name' => 'dogstar', 'before' => 10, 'addExp' => 2, 'after' => 12, 'reason' => 'help one more phper'));

//對(duì)應(yīng)的LOG
2015-02-07 20:48:51|INFO|add user exp|{"name":"dogstar","before":10,"addExp":2,"after":12,"reason":"help one more phper"}

但當(dāng)哪天我們看到以下的LOG是就會(huì)發(fā)現(xiàn)系統(tǒng)存在隱藏的BUG：

//WTF? 10 + 2 = 11 ???
2015-02-07 20:48:51|INFO|add user exp|{"name":"dogstar","before":10,"addExp":2,"after":11,"reason":"help one more phper"}

而當(dāng)用戶玩家來(lái)投訴客服時(shí)，客服妹子來(lái)找到我們后臺(tái)開(kāi)發(fā)時(shí)，我們可以證明得了是系統(tǒng)原因造成了用戶丟失1點(diǎn)經(jīng)驗(yàn)值。
特別地，若我們看到以下的LOG時(shí)，不難看出有人在用非法的渠道刷經(jīng)驗(yàn)：

2015-02-07 20:52:35|INFO|add user exp|{"name":"dogstar","before":10,"addExp":2,"after":12,"reason":"help one more phper"}
2015-02-07 20:52:35|INFO|add user exp|{"name":"dogstar","before":12,"addExp":2,"after":14,"reason":"help one more phper"}

....

2015-02-07 20:52:35|INFO|add user exp|{"name":"dogstar","before":998,"addExp":2,"after":1000,"reason":"help one more phper"}

所幸我們有日志并及時(shí)發(fā)現(xiàn)了，隨后如何處理就視具體的項(xiàng)目而定了。但當(dāng)產(chǎn)品來(lái)追問(wèn)時(shí)，我們可以及時(shí)給出反饋和做出處理。

還有更為重要的是 數(shù)據(jù)統(tǒng)計(jì) 。這塊就App數(shù)據(jù)分析和統(tǒng)計(jì)這塊已經(jīng)有了很好的第三方服務(wù)支持，一如：友盟。但我們?nèi)匀豢梢暂p松實(shí)現(xiàn)自己的數(shù)據(jù)統(tǒng)計(jì)，以便二次確認(rèn)和定制化。畢竟，總是依賴第三方不是那么輕便，而且存在敏感數(shù)據(jù)安全問(wèn)題。
這里簡(jiǎn)單提供一個(gè)上報(bào)接口，如：

    public function getRules() {
        return array(
            'report' => array(
                'username' => array('name' => 'username', 'require' => true),
                'msg' => array('name' => 'msg', 'require' => true),
            ),
        );
    }

    public function report() {
        DI()->logger->info($this->username, $this->msg);
    }

客戶端在需要的場(chǎng)景，如用戶打開(kāi)應(yīng)用，請(qǐng)求：

http://dev.phalapi.com/demo/?service=DogstarTest.Report&username=dogstar&msg=enter%20app

即可看到：

2015-02-07 21:01:13|INFO|dogstar|enter app

到后期，若我們需要統(tǒng)計(jì)用戶的登錄情況時(shí)，可以這樣統(tǒng)計(jì)：

$ cat ./Runtime/log/201502/20150207.log | grep "enter app" | awk -F '|' '{print $3}' | sort | uniq -c
     11 dogstar
      5 King
      2 Tom

(3)debug 開(kāi)發(fā)調(diào)試類

此類為開(kāi)發(fā)調(diào)試用，用法如上，這里不再贅述。以下是一些簡(jiǎn)單的示例：

DI()->logger->debug('just for test');

DI()->logger->debug('just for test', '一些其他的描述 ...');

DI()->logger->debug('just for test', array('name' => 'dogstar', 'password' => '******'));

1.17.2 使用DI()->logger->log()進(jìn)行更靈活的分類

若上面的error/info/debug都不能滿足項(xiàng)目的需求時(shí)，可以這樣更靈活地進(jìn)行日志紀(jì)錄：

DI()->logger->log('demo', 'add user exp', array('name' => 'dogstar', 'after' => 12));
DI()->logger->log('test', 'add user exp', array('name' => 'dogstar', 'after' => 12));

//對(duì)應(yīng)的日志
2015-02-07 21:13:27|DEMO|add user exp|{"name":"dogstar","before":10,"addExp":2,"after":12,"reason":"help one more phper"}
2015-02-07 21:15:39|TEST|add user exp|{"name":"dogstar","after":12}

注意到，DI()->logger->log()第一個(gè)參數(shù)為日志分類的名稱，在寫入日志時(shí)會(huì)自動(dòng)轉(zhuǎn)換為大寫。其接口函數(shù)簽名為：

    /**
     * 日志紀(jì)錄
     *
     * 可根據(jù)不同需要，將日志寫入不同的媒介
     *
     * @param string $type 日志類型，如：info/debug/error, etc
     * @param string $msg 日志關(guān)鍵描述
     * @param string/array $data 場(chǎng)景上下文信息
     * @return NULL
     */
    abstract public function log($type, $msg, $data);

1.17.3 別忘記了日志的級(jí)別設(shè)置

上面的三類日志分別對(duì)應(yīng)的標(biāo)識(shí)為：

• error 系統(tǒng)異常類：PhalApi_Logger::LOG_LEVEL_ERROR
• info 業(yè)務(wù)紀(jì)錄類：PhalApi_Logger::LOG_LEVEL_INFO
• debug 開(kāi)發(fā)調(diào)試類：PhalApi_Logger::LOG_LEVEL_DEBUG

根據(jù)不同的項(xiàng)目在不同環(huán)境下的需要，我們可以這樣有選擇性地將需要的日志分類寫入保存：

//日志紀(jì)錄
DI()->logger = new PhalApi_Logger_File(API_ROOT . '/Runtime',
    PhalApi_Logger::LOG_LEVEL_DEBUG | PhalApi_Logger::LOG_LEVEL_INFO | PhalApi_Logger::LOG_LEVEL_ERROR);

多個(gè)日志級(jí)別需要使用或運(yùn)算進(jìn)行組合。

1.17.4 擴(kuò)展你的日志存儲(chǔ)

普遍情況下，我們認(rèn)為將日志存放在文件是比較合理的，因?yàn)楸阌诓榭?、管理和統(tǒng)計(jì)。當(dāng)然，如果你的項(xiàng)目需要將日志紀(jì)錄在數(shù)據(jù)中，也可以快速擴(kuò)展實(shí)現(xiàn)。如實(shí)現(xiàn)數(shù)據(jù)庫(kù)的存儲(chǔ)思路：

//$ vim ./Apps/Common/Logger/DB.php

class Common_Logger_DB extends PhalApi_Logger {

    public function log($type, $msg, $data) {
        //TODO 數(shù)據(jù)庫(kù)的日志寫入 ...
    } 

隨后，利用DI注冊(cè)一下即可：

//日志紀(jì)錄 - DB
DI()->logger = new Common_Logger_DB($dbConfig,
    PhalApi_Logger::LOG_LEVEL_DEBUG | PhalApi_Logger::LOG_LEVEL_INFO | PhalApi_Logger::LOG_LEVEL_ERROR);