I. 概念

在 minbox-logging 日志组件内设计了多个 概念 以及 名词 定义，我们本篇文章来讲解下每个概念的 含义 以及 作用。

0. 源码 & 文档

• 源码：https://gitee.com/minbox-proj…
• 文档：https://gitee.com/minbox-proj…
• ApiBoot 整合示例：ApiBoot Logging Configuration

1. Client

client在整体架构体系中是 客户端 的概念，也就是我们的业务服务角色，在用户发起一个请求时，可能会经过多个业务服务来完成一系列的业务操作或者查询结果的组装，而每个服务在 minbox-logging 内就是 client 的概念，client要完成的工作是日志的 采集 、 上报 、 缓存 等。

1.1 日志采集

client目前版本支持采集 spring-mvc 的web应用程序请求日志信息（目前版本暂未支持 web-flux），通过 拦截器 获取每次请求的 链路编号 (traceId)、 单元编号 (spanId)、 请求参数 、 请求主体 、Header 列表、 请求路径 、 请求耗时 等详细信息，根据采集到的日志参数可以精准的定位到请求信息。

1.2 日志上报

client目前支持两种上报方式，分别是：just（直接上报）、timing（定时延迟上报），当采集到日志信息后通过拦截 LoggingWebInterceptor#afterCompletion 方法来进行异步上报信息，在这里采用异步上传的方式，为了防止出现日志上报网络延迟导致 用户发起的请求 响应 时间过长。

1.3 日志缓存

client端提供了短暂的 内存方式缓存 ，当我们使用timing 方式进行上报日志时，日志临时会存储到 memory（内存） 中，每次定时上报会从 内存缓存 中取到配置数量的请求日志一并上报到admin，一次上报的数量也有使用者自定义配置，默认为10。

当 client 正常停止 时，通过实现 DisposableBean 接口的 destory 方法内会一并将 内存缓存 的请求日志一并上报到admin。

2. Admin

admin在整体架构体系中担任 管理端 的角色，用于接收 client 上报的请求日志、存储日志 、 日志分析 等操作。

在 minbox-logging 体系中 admin 并不是必须存在的，如果是单体应用程序，可单独使用 client 在本地进行采集、存储、分析等。

2.1 日志接收

admin内部提供了一个上报日志的端点，该端点是一个标准的 REST 接口定义，可一次性接收一个 client 上传的多条请求日志。

执行顺序：

1. 检查 client 是否为第一次上报日志，如果是则执行保存服务器基本信息
2. 执行保存该 client 对应服务器的请求日志信息到数据库

2.2 日志存储

admin内部提供了 数据库 方式的存储实现类 LoggingDataSourceStorage，通过创建LoggingDataSourceStorage 的对象并且设置到 LoggingAdminFactoryBean 内即可完成配置，在创建 LoggingDataSourceStorage 对象时需要传递数据源，内部是通过 JDBC 直接操作 SQL 来完成的数据操作，这样不依赖任何第三方 ORM 框架，只需要 DataSource 对象即可。

2.3 自定义存储

目前版本 admin 仅提供了一个数据源方式存储，如果我们需要自定义存储可以通过实现 LoggingStorage 接口，然后创建自定义的对象实例后设置到 LoggingAdminFactoryBean 内即可。

2.4 日志分析（规划中）

在 admin 端，我们拿到数据后可以针对某一些点进行分析，比如：请求耗时较多的接口、接口的调用频率，针对调用频率可以有效的扩展对应服务的节点数量来应对流量。

3. Cache

cache用于临时缓存 请求日志 ，尽在timing 上报方式下生效。

4. ReportScheduled

定时上报日志，应用于 timing 上报方式，内部是一个定时线程，间隔一段时间调用 上报日志 方法。

每次默认会上报 10 条请求日志，每间隔 5 秒执行一次。

5. AdminDiscovery

AdminDiscovery来 client 用于发现 admin 服务的接口定义，在 client 内提供了两种方式，分别是：LoggingAppointAdminDiscovery、LoggingRegistryCenterAdminDiscovery。

通过 LoggingFactoryBean#setLoggingAdminDiscovery 方法进行设置。

5.1 LoggingAppointAdminDiscovery

指定 admin 具体地址信息的发现方式，通过构造函数可以指定多个 admin 地址，而且每个 admin 地址可以使用不同的 basic 基础认证信息。

当指定多个 admin 时，默认通过 平滑轮询策略 负载均衡方式上报，可自定义指定 随机策略 负载均衡方式。

admin地址的格式为：user:123456@localhost:9090，@前面为 basic 认证信息。

5.2 LoggingRegistryCenterAdminDiscovery

admin支持从服务注册中心（Eureka、Consul、Nacos Discovery、Zookeeper 等）内读取指定 applicationId 的服务节点列表，通过 ribbon 默认的负载均衡策略进行获取可用 admin 节点信息。

如果是 SpringCloud 构建的项目，建议使用这种方式。

6. LoggingNotice

client的日志通知方法，默认该接口有两个实现类，分别是：LoggingLocalNotice、LoggingAdminNotice，当一个请求完成时，client会发布一个 LoggingNoticeEvent 事件，该事件的监听者会获取 LoggingNotice 的全部实现类，根据 getOrder 方法的值顺序执行，值越大越靠前。

6.1 LoggingLocalNotice

client的本地控制台输出日志、控制台格式化日志的 LoggingNotice 实现类，会第一个被执行。

6.2 LoggingAdminNotice

client的上报日志到 admin 入口，会根据上报方式进行执行对应的业务逻辑。

• timing（延迟上报）

  会将本次的 MinBoxLog 对象缓存到cache，放入内存。

• just（直接上报）

  通过 LoggingFactoryBean 获取 LoggingAdminReport 实现类，调用 report 方法进行上报日志信息到admin。

7. ReportLogEvent

当 client 将日志上报到 admin 后，admin会通过 ApplicationContext 发布 ReportLogEvent 事件，在 admin 内提供了两个该事件的监听实现，分别是：ReportLogJsonFormatListener、ReportLogStorageListener。

7.1 ReportLogJsonFormatListener

用于格式化并在控制台显示 client 上报的日志信息。

7.2 ReportLogStorageListener

获取 LoggingAdminFactoryBean 提供的 LoggingStorage 接口实现类实例来进行持久化请求日志。

7.3 自定义监听

通过实现 Spring 提供的 SmartApplicationListener 监听器接口来自定义日志的存储或者其他分析操作，具体实现详见文档。