初识MinBox Logging

I. MinBox Logging 是什么？

1. 采集端 & 服务端

MinBox Logging是由minbox-projects开源组织推出的一款零侵入分布式链路日志组件，可用于微服务、RPC、单体应用使用。

MinBox Logging内存在两个概念，分别是：Client、Server。

• Client

  Client我们可以理解为日志的采集端，也就是我们的业务服务端，你的服务需要记录日志就可以理解作为Client端。

• Server

  Server是日志的管理服务端点，提供日志的存储、阀值分析提醒（暂未发布）、链路分析（暂未发布）等功能，统一接收日志采集端上报的请求日志信息并做记录，目前支持写入数据库、自定义存储机制，下一步整合消息队列来处理大批量日志的存储问题。

  服务端通过整合服务注册中心可以完成负载均衡多节点部署。

II. MinBox Logging 可以做什么？

MinBox Logging可以用来记录你的应用程序请求日志信息，可以将发起请求的IP、头信息、URL参数、请求主体参数、耗时、响应内容、异常堆栈信息等。

下面是MinBox Logging可以获取到的基本信息，如下所示：

{
	"endTime":1568252359448,
	"httpStatus":200,
	"requestBody":"",
	"requestHeaders":{
		"accept":"*/*",
		"host":"localhost:40030",
		"user-agent":"curl/7.54.0"
	},
	"requestIp":"10.180.98.120",
	"requestMethod":"GET",
	"requestParam":"{}",
	"requestUri":"/open/system/time/current",
	"responseBody":"{\"code\":\"SUCCESS\",\"data\":1568252359425,\"errorMsg\":\"\",\"success\":true,\"timestamp\":1568252359425}",
	"responseHeaders":{},
	"serviceId":"bff-open-api",
	"serviceIp":"10.180.98.245",
	"servicePort":"40030",
	"spanId":"56aaa01c-cad5-41c6-bd46-bf94626d77bd",
	"startTime":1568252359416,
	"timeConsuming":32,
	"traceId":"ad9ff32c-6195-4f75-adf2-1eb1ed98aaf9"
}

以上信息是由MinBox Logging进行在控制台格式化并打印输出（前提：配置输出日志参数），我们可以通过MinBox Logging提供的日志通知接口来实现自己的业务逻辑，详见org.minbox.framework.logging.client.notice.LoggingNotice源码。

2. 日志来源

Client采集的每一条请求日志都会携带产生的服务器IP、应用程序名称、应用程序端口号并且一并上传到Server，根据这些内容可以直接定位到日志的来源位置，可根据Client上报的数量进行占比分析，来决定服务请求分发负载均衡权重配置。

3. 耗时分析

每一次请求都会产生耗时，而接口耗时过长，可能会导致接口阻塞（如果应用程序没有加入熔断机制），针对这个问题MinBox Logging提供了计算耗时的方式，通过MinBoxLog#timeConsuming字段获取本次请求的耗时时间，单位是：毫秒，根据自己的业务自定义一个耗时阀值来进行通知耗时过长的请求给指定邮箱或者其他途径。

4. 异常解决

如果在用户请求过程中遇到了异常信息，而应用程序的控制台日志文件过大进行筛选异常信息时会耽误一定的时间，针对这个问题MinBox Logging提供获取请求中遇到异常的堆栈信息，通过异常信息可以精准的定位出现异常的代码位置。

5. 参数监控

用户发送的请求参数，我们无法进行限制，不过我们可以进行参数监控，通过制定参数对应的参数值来进行分析、监控，将分析结果通过存储或者通知方式告知。

6. 敏感头信息监控

与请求参数一致，通过请求头信息我们同样能做的事情有很多。

7. 请求IP分析

通过这个功能，我们可以记录每一个发起请求的IP地址接口访问量、访问的频率、峰值等信息。

8. 其他

等待发掘合适的业务.

III. 日志获取方式

日志信息在Client、Server都可以获取，拿到请求日志信息后，可以实现上面的扩展功能。

9. Client获取日志

在Client端可以通过LoggingNotice方式来获取MinBoxLog日志对象，根据对象的字段值来进行处理分析等业务，可创建多个LoggingNotice实现类来分析处理不同的业务，优先级根据LoggingNotice#getOrder方法的返回值而定。

/**
 * 自定义日志通知
 * 当不上报日志到`Logging Admin`时，可使用{@link LoggingNotice}来进行本地处理日志
 * 上报日志与本地处理不冲突，可并存
 *
 * @author 恒宇少年
 */
@Component
public class CustomerLoggingNotice implements LoggingNotice {
    /**
     * 通知方法
     *
     * @param minBoxLog ApiBoot Log
     */
    @Override
    public void notice(MinBoxLog minBoxLog) {
        System.out.println(minBoxLog.getTraceId());
      	// MinBoxLog 对象即为控制台打印的json信息，可以拿到里面的全部字段内容
    }

    /**
     * 通知执行优先级
     * {@link #getOrder()}方法返回值值越小优先级越高
     *
     * @return
     */
    @Override
    public int getOrder() {
        return 1;
    }
}

通过notice方法的参数可以直接获取到MinBoxLog对象，可根据参数值进行自定义业务判断处理。

10. Server获取日志

建议在Server端进行日志统一处理，虽然Client可以通过实现LoggingNotice接口来扩展日志处理，不过也是针对单个Client应用程序，对于分布式微服务应用程序来说却显得那么的无力。

因为每个Client都会进行上报到Server，所以在Server进行日志处理是最好的选择。

Server可以通过监听ReportLogEvent事件来获取Client的基本信息以及上报的日志列表（如果Client配置了延迟上报，每次可上报多条。），如下所示：

/**
 * 自定义上报日志事件{@link ReportLogEvent}监听
 *
 * @author 恒宇少年
 */
@Component
public class CustomerReportEventListener implements SmartApplicationListener {
    /**
     * logger instance
     */
    static Logger logger = LoggerFactory.getLogger(CustomerReportEventListener.class);

    /**
     * 判断事件类型为{@link ReportLogEvent}
     *
     * @param eventType
     * @return
     */
    @Override
    public boolean supportsEventType(Class<? extends ApplicationEvent> eventType) {
        return ReportLogEvent.class == eventType;
    }

    /**
     * 自定义处理业务
     * Client一次可上报多条日志{@link MinBoxLog}信息
     *
     * @param event {@link ReportLogEvent}
     */
    @Override
    public void onApplicationEvent(ApplicationEvent event) {
        ReportLogEvent reportLogEvent = (ReportLogEvent) event;
        LoggingClientNotice loggingClientNotice = reportLogEvent.getLogClientNotice();

        // MinBoxLog 日志列表
        List<MinBoxLog> logs = loggingClientNotice.getLoggers();

        logger.debug("上报日志服务：{}，IP地址：{}，端口号：{}，日志列表：", loggingClientNotice.getClientServiceId(),
                loggingClientNotice.getClientServiceIp(),
                loggingClientNotice.getClientServicePort(),
                logs);
    }
}

SmartApplicationListener是Spring提供的事件监听接口，由于该接口继承了Ordered所以拥有了#getOrder方法，通过该方法可以调整自定义日志监听的执行优先级。

IV. 源码 & 文档 & 集成实践

• 开源地址：https://gitee.com/minbox-projects/minbox-logging

• 使用文档地址：https://gitee.com/minbox-projects/minbox-logging/wikis

• ApiBoot最佳集成实践源码：https://gitee.com/minbox-projects/api-boot/tree/master/api-boot-project/api-boot-autoconfigure/src/main/java/org/minbox/framework/api/boot/autoconfigure/logging

• MinBox Logging Samples：https://gitee.com/minbox-projects/minbox-logging/tree/master/minbox-logging-samples