初识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-proj…
• 使用文档地址：https://gitee.com/minbox-proj…
• ApiBoot 最佳集成实践源码：https://gitee.com/minbox-proj…
• MinBox Logging Samples：https://gitee.com/minbox-proj…