ApiBoot 零侵入、链路式请求日志分析框架

ApiBoot提供单应用、微服务应用下的请求日志分析框架ApiBoot Logging，特性列表如下所示：

  • 链路：为每一个请求生成一个链路的单条或者多条请求日志信息，精准定位程序出现问题的位置。
  • 耗时：可以分析出每一个请求的耗时，改善服务的性能瓶颈
  • 异常信息：请求遇到异常，提供请求日志的异常堆栈信息记录
  • 请求参数：可以获取RequestBody、PathParam两种方式的参数
  • 响应内容：可以获取本次请求响应的内容信息。
  • 服务信息：可获取提供服务的ID、IP、Port等信息。
  • 异步通知：请求日志数据采集后通过Event/Listener方式异步通知给RPC、MQ、REST、Local。
  • 数据分析：阈值警告、异常通知等（短信、邮件等方式，2.1.1.RELEASE版本未实现.）

ApiBoot Logging内部采用拦截器、Filter组合完成一系列的操作。

  1. 如果一个请求的header信息内包含traceId（链路ID）则加入该链路，如果不存在则生成新的链路信息
  2. 如果一个请求的header信息内包含spanId（跨度ID），则使用该spanId作为parent spanId，对两个请求进行上下级关联。

架构设计图

ApiBoot Logging架构设计图

1. 添加依赖组件

在pom.xml配置文件内添加依赖，如下所示：

  1. <!--ApiBoot Logging-->
  2. <dependency>
  3.     <groupId>org.minbox.framework</groupId>
  4.     <artifactId>api-boot-starter-logging</artifactId>
  5. </dependency>

内部封装的组件

ApiBoot从2.1.3.RELEASE版本开始陆续会将api-boot-plugins模块下的组件从api-boot项目分离到minbox-projects开源组织内作为独立的项目进行升级维护，ApiBoot Logging内部通过封装minbox-projects/minbox-logging组件的minbox-logging-client实现。

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

注意：如果未添加ApiBoot版本依赖，请访问版本依赖查看添加方式。

2. 修改采集日志路径前缀

ApiBoot Logging默认采集/**下的所有请求路径，通过修改application.yml配置来变更采集日志路径的前缀：

  1. api:
  2.   boot:
  3.     logging:
  4.       # 修改日志路径前缀，可配置多个
  5.       logging-path-prefix:
  6.         - /user/**
  7.         - /order/**

在上面配置中，ApiBoot Logging只会采集/user/、/order/下所有路径的请求，并将日志上报到ApiBoot Logging Admin。

3. 排除不采集日志的路径

ApiBoot Logging可以指定某些路径的请求日志不进行采集、上报，比如：/actuator/health，通过修改application.yml配置来排除采集日志的路径列表，如下所示：

  1. api:
  2.   boot:
  3.     logging:
  4.       # 排除采集请求日志的路径列表
  5.       ignore-paths:
  6.         - /actuator/health

4. 修改日志等级

如果想让ApiBoot Logging在控制台输出日志信息，需要修改application.yml配置文件内的日志等级，如下所示：

  1. logging:
  2.   level:
  3.     org.minbox.framework.api.boot.plugin.logging: debug

5. 美化控制台打印日志信息

为了方便查看控制台打印的请求日志信息，ApiBoot Logging支持美化日志json信息，配置文件如下所示：

  1. api:
  2.   boot:
  3.     logging:
  4.       format-console-log-json: true

效果如下所示：

  1. 2019-07-24 12:56:11.231 DEBUG 3833 --- [nio-8080-exec-2] f.a.b.p.l.n.ApiBootLoggingNoticeListener : Request Uri：/index， Logging：
  2. {
  3.     "endTime":1563944171115,
  4.     "httpStatus":200,
  5.     "requestBody":"{\n\t\"name\":\"测试\",\n\t\"email\":\"jnyuqy@gmail.com\"\n}",
  6.     "requestHeaders":{
  7.         "accept":"*/*",
  8.         "accept-encoding":"gzip, deflate",
  9.         "cache-control":"no-cache",
  10.         "connection":"keep-alive",
  11.         "content-length":"52",
  12.         "content-type":"application/json",
  13.         "cookie":"JSESSIONID=8E206A652D76A5DF1775FC8988549DF4",
  14.         "host":"localhost:8080",
  15.         "postman-token":"cc60ceb7-32de-46f1-a7a4-86d694edd073",
  16.         "user-agent":"PostmanRuntime/7.15.2"
  17.     },
  18.     "requestIp":"0:0:0:0:0:0:0:1",
  19.     "requestMethod":"POST",
  20.     "requestUri":"/index",
  21.     "responseBody":"测试",
  22.     "responseHeaders":{},
  23.     "serviceId":"api-boot-sample-logging",
  24.     "serviceIp":"192.168.10.156",
  25.     "servicePort":"8080",
  26.     "spanId":"81c0016e-9bf7-4e86-bcad-98574f0df14c",
  27.     "startTime":1563944171049,
  28.     "timeConsuming":66,
  29.     "traceId":"409b6f2c-f70a-4648-9673-915534bc5aa9"
  30. }

6. 日志上报方式

ApiBoot Logging内部提供了两种上报方式，分别是just、timing。

6.1 just方式

just顾名思义是直接方式上报，也是ApiBoot Logging内默认的方式，当一个请求日志产生之后会实时上报到Logging Admin，利弊分析：

  • 优点
    • 数据分析延迟低
    • 提高数据有效性，防止丢失
  • 弊端
    • 增加Logging Admin访问压力

6.2 timing方式

timing方式是定时上报，ApiBoot Logging通过配置参数api.boot.logging.report-away=timing启用，默认间隔5秒执行一次上报，每次上报10条请求日志。

6.2.1 修改上报间隔时间

ApiBoot Logging默认间隔5秒发起一次上报请求到Logging Admin，修改配置如下所示：

  1. api:
  2.   boot:
  3.     logging:
  4.       # 修改每间隔10秒执行一次上报日志
  5.       report-interval-second: 10

6.2.2 修改每次上报条数

ApiBoot Logging默认每次发送缓存内的10条日志到Logging Admin，修改配置如下所示：

  1. api:
  2.   boot:
  3.     logging:
  4.       # 修改每次上报2条请求日志
  5.       number-of-request-log: 2

7. 日志上报到指定Admin

ApiBoot Logging 支持上报请求日志到指定Admin服务节点，配置如下所示：

  1. api:
  2.   boot:
  3.     logging:
  4.       admin:
  5.         # Logging Admin 服务地址
  6.         server-address: 127.0.0.1:9090

注意：Logging Admin服务地址不需要配置http://路径前缀。

8. 日志上报到服务注册中心Admin

ApiBoot Logging支持从服务注册中心（Eureka Server、Nacos Discovery、Consul…）中获取指定serviceID的服务列表，并且自动通过LoadBalance方式上报请求日志。

  1. api:
  2.   boot:
  3.     logging:
  4.       discovery:
  5.         # Logging Admin ServiceID
  6.         service-id: sample-logging-admin

Logging Admin ServiceID对应Logging Admin服务的spring.application.name属性配置。

9. 日志缓存

ApiBoot Logging内部默认通过memory（内存方式）进行缓存请求日志，目前版本无法修改缓存方式。

10. 支持SpringSecurity安全上报日志

安全性是日志上报的基础能力之一，ApiBoot Logging内部集成Spring Security的Basic安全认证方式来完成上报鉴权。

10.1 指定Admin的安全配置

ApiBoot Logging指定Admin服务节点的方式跟Eureka Client ServerUrl类似，在路径上添加Logging Admin配置的Spring Security用户名密码，配置如下所示：

  1. api:
  2.   boot:
  3.     logging:
  4.       admin:
  5.         # 用户名：user，密码：123456
  6.         server-address: user:123456@127.0.0.1:9090

10.2 服务注册中心Admin的安全配置

服务注册中心方式配置Logging Admin的Spring Security用户名、密码方式如下所示：

  1. api:
  2.   boot:
  3.     logging:
  4.       discovery:
  5.         # Logging Admin ServiceID
  6.         service-id: sample-logging-admin
  7.         # 用户名
  8.         username: user
  9.         # 密码
  10.         password: 123456

11. 日志通知

ApiBoot Logging提供了日志的通知功能，利用该功能可以对每一条请求日志进行输出、存储、分析等，通过实现LoggingNotice接口使用通知功能，示例如下所示：

  1. @Component
  2. public class LocalNoticeSample implements LoggingNotice {
  3.     /**
  4.      * order 值越小执行越靠前
  5.      *
  6.      * @return
  7.      */
  8.     @Override
  9.     public int getOrder() {
  10.         return 0;
  11.     }
  13.     /**
  14.      * 请求日志通知执行方法
  15.      * MinBoxLog为一次请求日志对象基本信息
  16.      *
  17.      * @param minBoxLog ApiBoot Log
  18.      */
  19.     @Override
  20.     public void notice(MinBoxLog minBoxLog) {
  21.         System.out.println(minBoxLog);
  22.     }
  23. }

ApiBoot Logging提供的LoggingNotice支持多个实现类配置，执行顺序根据getOrder()方法的返回值来定义，getOrder()方法返回值越小越靠前执行。MinBoxLog对象定义如下所示：

  1. public class MinBoxLog {
  2.     /**
  3.      * trace id
  4.      */
  5.     private String traceId;
  6.     /**
  7.      * span id
  8.      */
  9.     private String spanId;
  10.     /**
  11.      * parent span id
  12.      */
  13.     private String parentSpanId;
  14.     /**
  15.      * request uri
  16.      */
  17.     private String requestUri;
  18.     /**
  19.      * request method
  20.      */
  21.     private String requestMethod;
  22.     /**
  23.      * http status code
  24.      */
  25.     private int httpStatus;
  26.     /**
  27.      * request ip
  28.      */
  29.     private String requestIp;
  30.     /**
  31.      * service ip address
  32.      */
  33.     private String serviceIp;
  34.     /**
  35.      * service port
  36.      */
  37.     private String servicePort;
  38.     /**
  39.      * start time
  40.      */
  41.     private Long startTime;
  42.     /**
  43.      * end time
  44.      */
  45.     private Long endTime;
  46.     /**
  47.      * this request time consuming
  48.      */
  49.     private long timeConsuming;
  50.     /**
  51.      * service id
  52.      */
  53.     private String serviceId;
  54.     /**
  55.      * request headers
  56.      */
  57.     private Map<String, String> requestHeaders;
  58.     /**
  59.      * request param
  60.      */
  61.     private String requestParam;
  62.     /**
  63.      * request body
  64.      */
  65.     private String requestBody;
  66.     /**
  67.      * response headers
  68.      */
  69.     private Map<String, String> responseHeaders;
  70.     /**
  71.      * response body
  72.      */
  73.     private String responseBody;
  74.     /**
  75.      * exception stack
  76.      */
  77.     private String exceptionStack;
  78. }

12. 无缝支持Openfeign

ApiBoot Logging支持Spring Cloud Openfeign的方式请求，在SpringCloud微服务应用中如果你发起一个Http请求，而该请求在服务端通过openfeign访问其他服务，这时ApiBoot Logging会通过openfeign的Interceptor携带TraceId、SpanId到下一个服务，完成请求日志的链路信息透传。