日誌規約

參考文件

1. 七牛雲 json 格式日誌
2. 阿里雲 json 格式日誌
3. 騰訊雲 json 格式日誌
4. 華為雲 修改日誌轉儲
5. 百度雲 自定義日誌格式
6. elk-nginx輸出json格式的日誌
7. tomcat日誌格式轉化為json
8. 關於 log4j2 生成 json 格式的日誌

規則歸類

優先順序A：必要的

這些規則會使得你的日誌可用。

優先順序B：強烈推薦

這些規則會使得你的日誌更加通用。

優先順序C：推薦

這些規則會使得你的日誌更加容易使用

優先順序A的規則：必要的

日誌等級

日誌通常有完善的分級，分級不僅可以幫助工作人員根據異常等級快速檢索到亟待解決的問題，也可以幫助工作人員對問題解決順序進行排序。而且，日誌也並非越全越好，日誌越全，意味著cpu佔用率越高和磁碟空間佔用越大。在除錯過程中，工作人員可能會想要完整的日誌資訊來幫助他確定是否在程式的某些未知存在潛在危險，而在釋出的版本中，工作人員可能只想要寫錯誤及錯誤以上級別的日誌資訊。因此，日誌等級劃分是非常有必要的，可以在配置中新增想要寫的日誌級別，那麼低於這一級別的日誌資訊將不會輸出。

主要聚合 DEBUG、INFO、WARN、ERROR、FATAL、 五種等級的日誌訊息

等級	日誌型別
DEBUG	業務除錯級別日誌，記錄完整的業務細節，例如記錄每次HTTP請求的完整請求引數
INFO	業務記錄級別日誌，記錄業務的關鍵點流程，例如接收到了一次HTTP請求，記錄最基礎的請求引數，返回引數，以及響應時長
WARN	業務警告級別日誌，記錄業務中存在隱患或者與預期值存在差異但不影響後續業務的日誌
ERROR	業務錯誤級別日誌
FATAL	系統崩潰錯誤級別日誌

日誌行協議

由於供應商，語言，開發人員的不同，必然會導致日誌記錄規範及內容的多樣化，這必然會導致日誌的可讀性變差，為了使得記錄的日誌能夠可讀可用，必須保證日誌記錄的風格及內容一致，為此，我們需要定義一種日誌協議，開發者按照定義的協議在適當的位置輸出規範的日誌。

日誌行協議格式如下：

日誌行協議： 索引資訊 + 主體內容 + 擴充套件資訊
{
    "index": {
        "timestamp": 1565763393,
        "level": "INFO",
        "serveName": "cloudpark",
        ...,
    },
    "content": [
        {
            "type": "text",
            "label": "標題",
            "value": "文字型別資訊",
            ...,
        },
        {
            "type": "url",
            "label": "標題",
            "value": "url型別資訊",
            ...,
        },
        {
            "type": "json",
            "label": "標題",
            "value": "json型別資訊",
            ...,
        },
        {
            "type": "xml",
            "label": "標題",
            "value": "xml型別資訊",
            ...,
        },
        ...,
    ],
    "extension": {
        "codePosition": "cn.com.hzplatform.mqtt.MqttMessageUtil.sendMessage:21",
        "traceId": 12345,
        ...,
    }
}

示例：

當前記錄格式：
[2019-07-09 08:30:45,885] [192.168.5.3:cloudsystem-hzcityplatform-web-deployment-785d8c8b56-2txhq:1] [cloudsystem-hzcityplatform-web] [cn.com.hzplatform.WebApplication.logStarting:48] [INFO] [Starting WebApplication on cloudsystem-hzcityplatform-web-deployment-785d8c8b56-2txhq with PID 1 (/app/classes started by root in /)]

解析前：
{"index":{"timestamp":1562632245885,"level":"INFO","serveName":"cloudsystem-hzcityplatform-web","serveFlag":"192.168.5.3:cloudsystem-hzcityplatform-web-deployment-785d8c8b56-2txhq:1"},"content":[{"type":"text","label":"標題","value":"Starting WebApplication on cloudsystem-hzcityplatform-web-deployment-785d8c8b56-2txhq with PID 1 (/app/classes started by root in /)"}],"extension":{"codePosition":"cn.com.hzplatform.WebApplication.logStarting:48"}}

解析後：
{
    "index": {
        "timestamp": 1562632245885,
        "level": "INFO",
        "serveName": "cloudsystem-hzcityplatform-web",
        "serveFlag": "192.168.5.3:cloudsystem-hzcityplatform-web-deployment-785d8c8b56-2txhq:1",
    },
    "content": [
        {
            "type": "text",
            "label": "標題",
            "value": "Starting WebApplication on cloudsystem-hzcityplatform-web-deployment-785d8c8b56-2txhq with PID 1 (/app/classes started by root in /)",
        },
    ],
    "extension": {
        "codePosition": "cn.com.hzplatform.WebApplication.logStarting:48",
    }
}

結構說明

日誌行協議採用json字串格式（目前七牛雲，ELK，阿里，騰訊，華為等都支援json格式的日誌），目前通用的json格式日誌都為一層結構，一層結構雖然比較簡單，但擴充套件性不強，資訊型別不明確；因此日誌行協議包含index,content,extension三個頂層結構，將索引資訊，主體內容，擴充套件資訊的鍵值對分開，使得該日誌行協議更加通用，易於擴充套件，並且資訊型別更加明確，尤其在寫入到influxdb這樣的具有固定寫入協議的時序資料庫時，顯得尤為方便。

索引資訊

索引資訊，即快速查詢定位對應日誌的資訊。主要包含時間戳(timestamp,必選)，日誌等級(level,必選)，服務名稱(serveName,可選)，服務標識(serveFlag,可選)，介面名稱(apiName,可選)等。

主體內容

主體內容，即供運維人員分析定位錯誤的詳細資訊。主要包含介面請求，業務處理，資料庫操作，第三方呼叫等。記錄格式應該按照指定json格式生成。

擴充套件資訊

擴充套件資訊，即供運維人員定位錯誤的擴充套件資訊，主要包含程式碼位置(codePosition,可選)，鏈路標識(traceId,可選)等。

優先順序B的規則：強烈推薦

主體內容格式化

大部分日誌記錄時，主體內容為一整條文字資訊或者以鍵值對存在，當文字資訊中包含url,json,xml等格式的資訊時，可讀性會非常差，因此，將主體內容按照其本身型別進行區分，並根據對應的格式進行視覺化，能夠增強其可讀性。

新增服務名稱作為索引資訊

新增了服務名稱作為索引資訊後，運維人員可以通過該索引資訊，縮小檢索範圍，減少檢索時間；並且根據分析一個服務的日誌資訊，實現服務級預警。

新增程式碼位置作為擴充套件資訊

新增程式碼位置作為擴充套件資訊後，開發人員可以通過該擴充套件資訊，快速定位到指定的程式碼位置，分析並修復。

優先順序C的規則：推薦

新增業務鏈路ID作為擴充套件資訊

完成一次業務可能需要多個微服務協同工作，為了能夠快速分析出一次業務產生異常的原因，從鏈路開始時，賦予並傳遞一個traceId，根據traceId進行檢索，就能夠快速找到相關的日誌資訊，方便運維人員及開發人員進行問題復現及處理。

新增服務標識作為索引資訊

新增了服務標識作為索引資訊後，運維人員可以通過該索引資訊，縮小檢索範圍，減少檢索時間；方便灰度釋出時，監控某個升級服務的執行情況。

新增介面作為索引資訊

新增介面作為索引資訊，運維人員可以通過該索引資訊，縮小檢索範圍，減少檢索時間；方便介面穩定性分析。