ApiBoot 文档

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

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

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

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

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

架构设计图

ApiBoot Logging架构设计图

1. 添加依赖组件

pom.xml配置文件内添加依赖,如下所示:

<!--ApiBoot Logging-->
<dependency>
    <groupId>org.minbox.framework</groupId>
    <artifactId>api-boot-starter-logging</artifactId>
</dependency>

内部封装的组件

ApiBoot2.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配置来变更采集日志路径的前缀:

api:
  boot:
    logging:
      # 修改日志路径前缀,可配置多个
      logging-path-prefix:
        - /user/**
        - /order/**

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

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

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

api:
  boot:
    logging:
      # 排除采集请求日志的路径列表
      ignore-paths:
        - /actuator/health

4. 修改日志等级

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

logging:
  level:
    org.minbox.framework.api.boot.plugin.logging: debug

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

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

api:
  boot:
    logging:
      format-console-log-json: true

效果如下所示:

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

6. 日志上报方式

ApiBoot Logging内部提供了两种上报方式,分别是justtiming

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,修改配置如下所示:

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

6.2.2 修改每次上报条数

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

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

7. 日志上报到指定Admin

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

api:
  boot:
    logging:
      admin:
        # Logging Admin 服务地址
        server-address: 127.0.0.1:9090

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

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

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

api:
  boot:
    logging:
      discovery:
        # Logging Admin ServiceID
        service-id: sample-logging-admin

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

9. 日志缓存

ApiBoot Logging内部默认通过memory(内存方式)进行缓存请求日志,目前版本无法修改缓存方式

10. 支持SpringSecurity安全上报日志

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

10.1 指定Admin的安全配置

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

api:
  boot:
    logging:
      admin:
        # 用户名:user,密码:123456
        server-address: user:123456@127.0.0.1:9090

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

服务注册中心方式配置Logging AdminSpring Security用户名、密码方式如下所示:

api:
  boot:
    logging:
      discovery:
        # Logging Admin ServiceID
        service-id: sample-logging-admin
        # 用户名
        username: user
        # 密码
        password: 123456

11. 日志通知

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

@Component
public class LocalNoticeSample implements LoggingNotice {
    /**
     * order 值越小执行越靠前
     *
     * @return
     */
    @Override
    public int getOrder() {
        return 0;
    }

    /**
     * 请求日志通知执行方法
     * MinBoxLog为一次请求日志对象基本信息
     *
     * @param minBoxLog ApiBoot Log
     */
    @Override
    public void notice(MinBoxLog minBoxLog) {
        System.out.println(minBoxLog);
    }
}

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

public class MinBoxLog {
    /**
     * trace id
     */
    private String traceId;
    /**
     * span id
     */
    private String spanId;
    /**
     * parent span id
     */
    private String parentSpanId;
    /**
     * request uri
     */
    private String requestUri;
    /**
     * request method
     */
    private String requestMethod;
    /**
     * http status code
     */
    private int httpStatus;
    /**
     * request ip
     */
    private String requestIp;
    /**
     * service ip address
     */
    private String serviceIp;
    /**
     * service port
     */
    private String servicePort;
    /**
     * start time
     */
    private Long startTime;
    /**
     * end time
     */
    private Long endTime;
    /**
     * this request time consuming
     */
    private long timeConsuming;
    /**
     * service id
     */
    private String serviceId;
    /**
     * request headers
     */
    private Map<String, String> requestHeaders;
    /**
     * request param
     */
    private String requestParam;
    /**
     * request body
     */
    private String requestBody;
    /**
     * response headers
     */
    private Map<String, String> responseHeaders;
    /**
     * response body
     */
    private String responseBody;
    /**
     * exception stack
     */
    private String exceptionStack;
}

12. 无缝支持Openfeign

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