摘要：使我們的事件結(jié)構(gòu)更加清晰，同時(shí)，也能避免數(shù)據(jù)字段對(duì)元字段造成污染。一般的，我們?cè)诖蛴≥敵鋈罩镜臅r(shí)候，只須關(guān)注事件名稱(chēng)及數(shù)據(jù)字段即可。

我們都有過(guò)上機(jī)器查日志的經(jīng)歷，當(dāng)集群數(shù)量增多的時(shí)候，這種原始的操作帶來(lái)的低效率不僅給我們定位現(xiàn)網(wǎng)問(wèn)題帶來(lái)極大的挑戰(zhàn)，同時(shí)，我們也無(wú)法對(duì)我們服務(wù)框架的各項(xiàng)指標(biāo)進(jìn)行有效的量化診斷，更無(wú)從談?dòng)嗅槍?duì)性的優(yōu)化和改進(jìn)。這個(gè)時(shí)候，構(gòu)建具備信息查找，服務(wù)診斷，數(shù)據(jù)分析等功能的實(shí)時(shí)日志監(jiān)控系統(tǒng)尤為重要。

ELK （ELK Stack: ElasticSearch, LogStash, Kibana, Beats） 是一套成熟的日志解決方案，其開(kāi)源及高性能在各大公司廣泛使用。而我們業(yè)務(wù)所使用的服務(wù)框架，如何接入 ELK 系統(tǒng)呢？

業(yè)務(wù)背景
我們的業(yè)務(wù)框架背景：

業(yè)務(wù)框架是基于 NodeJs 的 WebServer
服務(wù)使用 winston 日志模塊將日志本地化
服務(wù)產(chǎn)生的日志存儲(chǔ)在各自機(jī)器的磁盤(pán)上
服務(wù)部署在不同地域多臺(tái)機(jī)器
接入步驟
我們將整個(gè)框架接入 ELK 簡(jiǎn)單歸納為下面幾個(gè)步驟：

日志結(jié)構(gòu)設(shè)計(jì)：由傳統(tǒng)的純文本日志改成結(jié)構(gòu)化對(duì)象并輸出為 JSON.
日志采集：在框架請(qǐng)求生命周期的一些關(guān)鍵節(jié)點(diǎn)輸出日志
ES 索引模版定義：建立 JSON 到 ES 實(shí)際存儲(chǔ)的映射
一、日志結(jié)構(gòu)設(shè)計(jì)
傳統(tǒng)的，我們?cè)谧鋈罩据敵龅臅r(shí)候，是直接輸出日志的等級(jí)（level）和日志的內(nèi)容字符串（message）。然而我們不僅關(guān)注什么時(shí)間，發(fā)生了什么，可能還需要關(guān)注類(lèi)似的日志發(fā)生了多少次，日志的細(xì)節(jié)與上下文，以及關(guān)聯(lián)的日志。 因此我們不只是簡(jiǎn)單地將我們的日志結(jié)構(gòu)化一下為對(duì)象，還要提取出日志關(guān)鍵的字段。

將日志抽象為事件

我們將每一條日志的發(fā)生都抽像為一個(gè)事件。事件包含：

事件元字段
事件發(fā)生時(shí)間：datetime, timestamp
事件等級(jí)：level， 例如: ERROR, INFO, WARNING, DEBUG
事件名稱(chēng): event, 例如：client-request
事件發(fā)生的相對(duì)時(shí)間（單位：納秒）：reqLife, 此字段為事件相對(duì)請(qǐng)求開(kāi)始發(fā)生的時(shí)間（間隔）
事件發(fā)生的位置: line，代碼位置; server, 服務(wù)器的位置
請(qǐng)求元字段
請(qǐng)求唯一ID: reqId, 此字段貫穿整個(gè)請(qǐng)求鏈路上發(fā)生的所有事件
請(qǐng)求用戶(hù)ID: reqUid, 此字段為用戶(hù)標(biāo)識(shí)，可以跟蹤用戶(hù)的訪問(wèn)或請(qǐng)求鏈路
數(shù)據(jù)字段
不同類(lèi)型的事件，需要輸出的細(xì)節(jié)不盡相同，我們將這些細(xì)節(jié)（非元字段）統(tǒng)一放到d -- data，之中。使我們的事件結(jié)構(gòu)更加清晰，同時(shí)，也能避免數(shù)據(jù)字段對(duì)元字段造成污染。

e.g. 如 client-init事件，該事件會(huì)在每次服務(wù)器接收到用戶(hù)請(qǐng)求時(shí)打印，我們將用戶(hù)的 ip, url等事件獨(dú)有的統(tǒng)一歸為數(shù)據(jù)字段放到 d 對(duì)象中

舉個(gè)完整的例子

{
    "datetime":"2018-11-07 21:38:09.271",
    "timestamp":1541597889271,
    "level":"INFO",
    "event":"client-init",
    "reqId":"rJtT5we6Q",
    "reqLife":5874,
    "reqUid": "999793fc03eda86",
    "d":{
        "url":"/",
        "ip":"9.9.9.9",
        "httpVersion":"1.1",
        "method":"GET",
        "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36",
        "headers":"*"
    },
    "browser":"{"name":"Chrome","version":"70.0.3538.77","major":"70"}",
    "engine":"{"version":"537.36","name":"WebKit"}",
    "os":"{"name":"Mac OS","version":"10.14.0"}",
    "content":"(Empty)",
    "line":"middlewares/foo.js:14",
    "server":"127.0.0.1"
}

一些字段，如：browser, os, engine為什么在外層 有時(shí)候我們希望日志盡量扁平（最大深度為2），以避免 ES 不必要的索引帶來(lái)的性能損耗。在實(shí)際輸出的時(shí)候，我們會(huì)將深度大于1的值輸出為字符串。而有時(shí)候一些對(duì)象字段是我們關(guān)注的，所以我們將這些特殊字段放在外層，以保證輸出深度不大于2的原則。

一般的，我們?cè)诖蛴≥敵鋈罩镜臅r(shí)候，只須關(guān)注事件名稱(chēng)及數(shù)據(jù)字段即可。其他，我們可以在打印日志的方法中，通過(guò)訪問(wèn)上下文統(tǒng)一獲取，計(jì)算，輸出。

日志改造輸出

前面我們提到了如何定義一個(gè)日志事件， 那么，我們?nèi)绾位谝延腥罩痉桨缸錾?jí)，同時(shí)，兼容舊代碼的日志調(diào)用方式。

升級(jí)關(guān)鍵節(jié)點(diǎn)的日志

// 改造前
logger.info("client-init => " + JSON.stringfiy({
    url,
    ip,
    browser,
    //...
}));

// 改造后
logger.info({
    event: "client-init",
    url,
    ip,
    browser,
    //...
});

兼容舊的日志調(diào)用方式
logger.debug("checkLogin");
因?yàn)?winston 的 日志方法本身就支持 string 或者 object 的傳入方式, 所以對(duì)于舊的字符串傳入寫(xiě)法，formatter 接收到的實(shí)際上是{ level: "debug", message: "checkLogin" }。formatter 是 winston 的日志輸出前調(diào)整日志格式的一道工序， 這一點(diǎn)使我們?cè)谌罩据敵銮坝袡C(jī)會(huì)將這類(lèi)調(diào)用方式輸出的日志，轉(zhuǎn)為一個(gè)純輸出事件 -- 我們稱(chēng)它們?yōu)閞aw-log事件，而不需要修改調(diào)用方式。

改造日志輸出格式
前面提到 winston 輸出日志前，會(huì)經(jīng)過(guò)我們預(yù)定義的formatter，因此除了兼容邏輯的處理外，我們可以將一些公共邏輯統(tǒng)一放在這里處理。而調(diào)用上，我們只關(guān)注字段本身即可。

元字段提取及處理
字段長(zhǎng)度控制
兼容邏輯處理
如何提取元字段，這里涉及上下文的創(chuàng)建與使用，這里簡(jiǎn)單介紹一下 domain 的創(chuàng)建與使用。

//--- middlewares/http-context.js
const domain = require("domain");
const shortid = require("shortid");

module.exports = (req, res, next) => {
    const d = domain.create();
    d.id =  shortid.generate(); // reqId;
    d.req = req;
    
    //...

    res.on("finish", () => process.nextTick(() => {
        d.id = null;
        d.req = null;
        d.exit();
    });

    d.run(() => next());
}

//--- app.js
app.use(require("./middlewares/http-context.js"));

//--- formatter.js
if (process.domain) {
    reqId = process.domain.id;
}

這樣，我們就可以將 reqId 輸出到一次請(qǐng)求中所有的事件, 從而達(dá)到關(guān)聯(lián)事件的目的。

二、日志采集
現(xiàn)在，我們知道怎么輸出一個(gè)事件了，那么下一步，我們?cè)摽紤]兩個(gè)問(wèn)題：

我們要在哪里輸出事件？
事件要輸出什么細(xì)節(jié)？
換句話說(shuō)，整個(gè)請(qǐng)求鏈路中，哪些節(jié)點(diǎn)是我們關(guān)注的，出現(xiàn)問(wèn)題，可以通過(guò)哪個(gè)節(jié)點(diǎn)的信息快速定位到問(wèn)題？除此之外，我們還可以通過(guò)哪些節(jié)點(diǎn)的數(shù)據(jù)做統(tǒng)計(jì)分析？

結(jié)合一般常見(jiàn)的請(qǐng)求鏈路（用戶(hù)請(qǐng)求，服務(wù)側(cè)接收請(qǐng)求，服務(wù)請(qǐng)求下游服務(wù)器/數(shù)據(jù)庫(kù)（*多次），數(shù)據(jù)聚合渲染，服務(wù)響應(yīng)），如下方的流程圖

那么，我們可以這樣定義我們的事件：

用戶(hù)請(qǐng)求
client-init: 打印于框架接收到請(qǐng)求（未解析）， 包括：請(qǐng)求地址，請(qǐng)求頭，Http 版本和方法，用戶(hù) IP 和 瀏覽器
client-request: 打印于框架接收到請(qǐng)求（已解析），包括：請(qǐng)求地址，請(qǐng)求頭，Cookie, 請(qǐng)求包體
client-response: 打印于框架返回請(qǐng)求，包括：請(qǐng)求地址，響應(yīng)碼，響應(yīng)頭，響應(yīng)包體
下游依賴(lài)
http-start: 打印于請(qǐng)求下游起始：請(qǐng)求地址，請(qǐng)求包體，模塊別名（方便基于名字聚合而且域名）
http-success: 打印于請(qǐng)求返回 200：請(qǐng)求地址，請(qǐng)求包體，響應(yīng)包體(code & msg & data)，耗時(shí)
http-error: 打印于請(qǐng)求返回非 200，亦即連接服務(wù)器失?。赫?qǐng)求地址，請(qǐng)求包體，響應(yīng)包體(code & message & stack)，耗時(shí)。
http-timeout: 打印于請(qǐng)求連接超時(shí)：請(qǐng)求地址，請(qǐng)求包體，響應(yīng)包體(code & msg & stack)，耗時(shí)。
字段這么多，該怎么選擇？ 一言以蔽之，事件輸出的字段原則就是：輸出你關(guān)注的，方便檢索的，方便后期聚合的字段。

一些建議
請(qǐng)求下游的請(qǐng)求體和返回體有固定格式， e.g. 輸入：{ action: "getUserInfo", payload: {} } 輸出: { code: 0, msg: "", data: {}} 我們可以在事件輸出 action，code 等，以便后期通過(guò) action 檢索某模塊具體某個(gè)接口的各項(xiàng)指標(biāo)和聚合。
一些原則
保證輸出字段類(lèi)型一致 由于所有事件都存儲(chǔ)在同一個(gè) ES 索引， 因此，相同字段不管是相同事件還是不同事件，都應(yīng)該保持一致，例如：code不應(yīng)該既是數(shù)字，又是字符串，這樣可能會(huì)產(chǎn)生字段沖突，導(dǎo)致某些記錄（document）無(wú)法被沖突字段檢索到。
ES 存儲(chǔ)類(lèi)型為 keyword, 不應(yīng)該超過(guò) ES mapping 設(shè)定的 ignore_above 中指定的字節(jié)數(shù)（默認(rèn)4096個(gè)字節(jié)）。否則同樣可能會(huì)產(chǎn)生無(wú)法被檢索的情況
三、ES 索引模版定義
這里引入 ES 的兩個(gè)概念，映射(Mapping)與模版(Template)。

首先，ES 基本的存儲(chǔ)類(lèi)型大概枚舉下，有以下幾種

String: keyword & text
Numeric: long, integer, double
Date: date
Boolean: boolean

一般的，我們不需要顯示指定每個(gè)事件字段的在ES對(duì)應(yīng)的存儲(chǔ)類(lèi)型，ES 會(huì)自動(dòng)根據(jù)字段第一次出現(xiàn)的document中的值來(lái)決定這個(gè)字段在這個(gè)索引中的存儲(chǔ)類(lèi)型。但有時(shí)候，我們需要顯示指定某些字段的存儲(chǔ)類(lèi)型，這個(gè)時(shí)候我們需要定義這個(gè)索引的 Mapping, 來(lái)告訴 ES 這此字段如何存儲(chǔ)以及如何索引。

e.g.

還記得事件元字段中有一個(gè)字段為 timestamp ？實(shí)際上，我們輸出的時(shí)候，timestamp 的值是一個(gè)數(shù)字，它表示跟距離 1970/01/01 00:00:00 的毫秒數(shù)，而我們期望它在ES的存儲(chǔ)類(lèi)型為 date 類(lèi)型方便后期的檢索和可視化, 那么我們創(chuàng)建索引的時(shí)候，指定我們的Mapping。

PUT my_logs
{
  "mappings": {
    "_doc": { 
      "properties": { 
        "title":    {
            "type": "date",
            "format": "epoch_millis"
         }, 
      }
    }
  }
}

但一般的，我們可能會(huì)按日期自動(dòng)生成我們的日志索引，假定我們的索引名稱(chēng)格式為 my_logs_yyyyMMdd （e.g. my_logs_20181030）。那么我們需要定義一個(gè)模板（Template），這個(gè)模板會(huì)在（匹配的）索引創(chuàng)建時(shí)自動(dòng)應(yīng)用預(yù)設(shè)好的 Mapping。

PUT _template/my_logs_template
{
  "index_patterns": "my_logs*",
  "mappings": {
    "_doc": { 
      "properties": { 
        "title":    {
            "type": "date",
            "format": "epoch_millis"
         }, 
      }
    }
  }
}

提示：將所有日期產(chǎn)生的日志都存在一張索引中，不僅帶來(lái)不必要的性能開(kāi)銷(xiāo)，也不利于定期刪除比較久遠(yuǎn)的日志。

小結(jié)
至此，日志改造及接入的準(zhǔn)備工作都已經(jīng)完成了，我們只須在機(jī)器上安裝 FileBeat -- 一個(gè)輕量級(jí)的文件日志Agent, 它負(fù)責(zé)將日志文件中的日志傳輸?shù)?ELK。接下來(lái)，我們便可使用 Kibana 快速的檢索我們的日志。