基於Egg框架的日誌鏈路追蹤實踐分享

時間 2019-12-07

標籤基於 egg 框架日誌鏈路追蹤實踐分享简体版

原文原文鏈接

快速導航

[Logger-Custom] 需求背景
[Logger-Custom] 自定義日誌插件開發
[Logger-Custom] 項目擴展
[Logger-Custom] 項目應用
[ContextFormatter] contextFormatter自定義日誌格式
[Logrotator] 日誌切割

需求背景

實現全鏈路日誌追蹤，便於日誌監控、問題排查、接口響應耗時數據統計等，首先 API 接口服務接收到調用方請求，根據調用方傳的 traceId，在該次調用鏈中處理業務時，如需打印日誌的，日誌信息按照約定的規範進行打印，並記錄 traceId，實現日誌鏈路追蹤。html

日誌路徑約定

/var/logs/${projectName}/bizLog/${projectName}-yyyyMMdd.log

日誌格式約定

日誌時間[]traceId[]服務端IP[]客戶端IP[]日誌級別[]日誌內容

採用 Egg.js 框架 egg-logger 中間件，在實現過程當中發現對於按照以上日誌格式打印是沒法知足需求的（至少目前我還沒找到可實現方式），若是要本身實現，可能要本身造輪子了，好在官方的 egg-logger 中間件提供了自定義日誌擴展功能，參考高級自定義日誌，自己也提供了日誌分割、多進程日誌處理等功能。node

egg-logger 提供了多種傳輸通道，咱們的需求主要是對請求的業務日誌自定義格式存儲，主要用到 fileTransport 和 consoleTransport 兩個通道，分別打印日誌到文件和終端。git

自定義日誌插件開發

基於 egg-logger 定製開發一個插件項目，參考插件開發，如下以 egg-logger-custom 爲項目，展現核心代碼編寫github

編寫logger.js

egg-logger-custom/lib/logger.js

const moment = require('moment');
const FileTransport = require('egg-logger').FileTransport;
const utils = require('./utils');
const util = require('util');

/**
 * 繼承 FileTransport
 */
class AppTransport extends FileTransport {
    constructor(options, ctx) {
        super(options);

        this.ctx = ctx; // 獲得每次請求的上下文
    }

    log(level, args, meta) {
        // 獲取自定義格式消息
        const customMsg = this.messageFormat({
            level,
        });

        // 針對 Error 消息打印出錯誤的堆棧
        if (args[0] instanceof Error) {
            const err = args[0] || {};
            args[0] = util.format('%s: %s\n%s\npid: %s\n', err.name, err.message, err.stack, process.pid);
        } else {
            args[0] = util.format(customMsg, args[0]);
        }

        // 這個是必須的，不然日誌文件不會寫入
        super.log(level, args, meta);
    }

    /**
     * 自定義消息格式
     * 能夠根據本身的業務需求自行定義
     * @param { String } level
     */
    messageFormat({
        level
    }) {
        const { ctx } = this;
        const params = JSON.stringify(Object.assign({}, ctx.request.query, ctx.body));

        return [
            moment().format('YYYY/MM/DD HH:mm:ss'),
            ctx.request.get('traceId'),
            utils.serviceIPAddress,
            utils.clientIPAddress(ctx.req),
            level,
        ].join(utils.loggerDelimiter) + utils.loggerDelimiter;
    }
}

module.exports = AppTransport;

工具

egg-logger-custom/lib/utils.js

const interfaces = require('os').networkInterfaces();

module.exports = {

    /**
     * 日誌分隔符
     */
    loggerDelimiter: '[]',

    /**
     * 獲取當前服務器IP
     */
    serviceIPAddress: (() => {
        for (const devName in interfaces) {
            const iface = interfaces[devName];

            for (let i = 0; i < iface.length; i++) {
                const alias = iface[i];

                if (alias.family === 'IPv4' && alias.address !== '127.0.0.1' && !alias.internal) {
                    return alias.address;
                }
            }
        }
    })(),

    /**
     * 獲取當前請求客戶端IP
     * 不安全的寫法
     */
    clientIPAddress: req => {
        const address = req.headers['x-forwarded-for'] || // 判斷是否有反向代理 IP
        req.connection.remoteAddress || // 判斷 connection 的遠程 IP
        req.socket.remoteAddress || // 判斷後端的 socket 的 IP
        req.connection.socket.remoteAddress;

        return address.replace(/::ffff:/ig, '');
    },

    clientIPAddress: ctx => {    
        return ctx.ip;
    },
}

注意：以上獲取當前請求客戶端IP的方式，若是你須要對用戶的 IP 作限流、防刷限制，請不要使用如上方式，參見科普文：如何僞造和獲取用戶真實 IP ？，在 Egg.js 裏你也能夠經過 ctx.ip 來獲取，參考前置代理模式。npm

初始化 Logger

egg-logger-custom/app.js

const Logger = require('egg-logger').Logger;
const ConsoleTransport = require('egg-logger').ConsoleTransport;
const AppTransport = require('./app/logger');

module.exports = (ctx, options) => {
    const logger = new Logger();

    logger.set('file', new AppTransport({
        level: options.fileLoggerLevel || 'INFO',
        file: `/var/logs/${options.appName}/bizLog/${options.appName}.log`,
    }, ctx));

    logger.set('console', new ConsoleTransport({
        level: options.consoleLevel || 'INFO',
    }));

    return logger;
}

以上對於日誌定製格式開發已經好了，若是你有實際業務須要能夠根據本身團隊的需求，封裝爲團隊內部的一個 npm 中間件來使用。後端

項目擴展

自定義日誌中間件封裝好以後，在實際項目應用中咱們還須要一步操做，Egg 提供了框架擴展功能，包含五項：Application、Context、Request、Response、Helper，能夠對這幾項進行自定義擴展，對於日誌由於每第二天志記錄咱們須要記錄當前請求攜帶的 traceId 作一個鏈路追蹤，須要用到 Context（是 Koa 的請求上下文）擴展項。安全

新建 app/extend/context.js 文件bash

const AppLogger = require('egg-logger-custom'); // 上面定義的中間件

module.exports = {
    get logger() { // 名字自定義 也能夠是 customLogger
        return AppLogger(this, {
            appName: 'test', // 項目名稱
            consoleLevel: 'DEBUG', // 終端日誌級別
            fileLoggerLevel: 'DEBUG', // 文件日誌級別
        });
    }
}

建議：對於日誌級別，能夠採用配置中心如 Consul 進行配置，上線時日誌級別設置爲 INFO，當須要生產問題排查時，能夠動態開啓 DEBUG 模式。關於 Consul 能夠關注我以前寫的服務註冊發現 Consul 系列服務器

項目應用

錯誤日誌記錄，直接會將錯誤日誌完整堆棧信息記錄下來，而且輸出到 errorLog 中，爲了保證異常可追蹤，必須保證全部拋出的異常都是 Error 類型，由於只有 Error 類型纔會帶上堆棧信息，定位到問題。app

const Controller = require('egg').Controller;

class ExampleController extends Controller {
    async list() {
        const { ctx } = this;

        ctx.logger.error(new Error('程序異常！'));

        ctx.logger.debug('測試');

        ctx.logger.info('測試');
    }
}

最終日誌打印格式以下所示：

2019/05/30 01:50:21[]d373c38a-344b-4b36-b931-1e8981aef14f[]192.168.1.20[]221.69.245.153[]INFO[]測試

contextFormatter自定義日誌格式

Egg-Logger 最新版本支持經過 contextFormatter 函數自定義日誌格式，參見以前 PR：support contextFormatter #51

應用也很簡單，經過配置 contextFormatter 函數便可，如下是簡單的應用

config.logger = {
    contextFormatter: function(meta) {
        console.log(meta);
        return [
            meta.date,
            meta.message
        ].join('[]')
    },
    ...
};

一樣的在你的業務裏對於須要打印日誌的地方，和以前同樣

ctx.logger.info('這是一個測試數據');

輸出結果以下所示：

2019-06-04 12:20:10,421[]這是一個測試數據

日誌切割

框架提供了 egg-logrotator 中間件，默認切割爲按天切割，其它方式可參考官網自行配置。

框架默認日誌路徑

egg-logger 模塊 lib/egg/config/config.default.js

config.logger = {
    dir: path.join(appInfo.root, 'logs', appInfo.name),
    ...
};

很簡單按照咱們的需求在項目配置文件從新定義 logger 的 dir 路徑

config.logger = {
    dir: /var/logs/test/bizLog/
}

這樣是否就能夠呢？按照咱們上面自定義的日誌文件名格式（${projectName}-yyyyMMdd.log），貌似是不行的，在日誌分割過程當中默認的文件名格式爲 .log.YYYY-MM-DD ，參考源碼

https://github.com/eggjs/egg-logrotator/blob/master/app/lib/day_rotator.js

_setFile(srcPath, files) {
    // don't rotate logPath in filesRotateBySize
    if (this.filesRotateBySize.indexOf(srcPath) > -1) {
      return;
    }

    // don't rotate logPath in filesRotateByHour
    if (this.filesRotateByHour.indexOf(srcPath) > -1) {
      return;
    }

    if (!files.has(srcPath)) {
      // allow 2 minutes deviation
      const targetPath = srcPath + moment()
        .subtract(23, 'hours')
        .subtract(58, 'minutes')
        .format('.YYYY-MM-DD'); // 日誌格式定義
      debug('set file %s => %s', srcPath, targetPath);
      files.set(srcPath, { srcPath, targetPath });
    }
 }

日誌分割擴展

中間件 egg-logrotator 預留了擴展接口，對於自定義的日誌文件名，能夠用框架提供的 app.LogRotator 作一個定製。

app/schedule/custom.js

const moment = require('moment');

module.exports = app => {
    const rotator = getRotator(app);

    return {
        schedule: {
            type: 'worker', // only one worker run this task
            cron: '1 0 0 * * *', // run every day at 00:00
        },
        async task() {
            await rotator.rotate();
        }
    };
};

function getRotator(app) {
    class CustomRotator extends app.LogRotator {
        async getRotateFiles() {
            const files = new Map();
            const srcPath = `/var/logs/test/bizLog/test.log`;
            const targetPath = `/var/logs/test/bizLog/test-${moment().subtract(1, 'days').format('YYYY-MM-DD')}.log`;
            files.set(srcPath, { srcPath, targetPath });
            return files;
        }
    }

    return new CustomRotator({ app });
}

通過分割以後文件展現以下：

$ ls -lh /var/logs/test/bizLog/
total 188K
-rw-r--r-- 1 root root 135K Jun  1 11:00 test-2019-06-01.log
-rw-r--r-- 1 root root  912 Jun  2 09:44 test-2019-06-02.log
-rw-r--r-- 1 root root  40K Jun  3 11:49 test.log

擴展：基於以上日誌格式，能夠採用 ELK 作日誌蒐集、分析、檢索。

做者：五月君
連接：https://www.imooc.com/article...
來源：慕課網