概念阐述

ServiceComb 提供了基于 Vert.x 的 access log 和 request log 功能。当用户使用 REST over Vertx 通信方式时,可以通过简单的配置启用 access log 打印功能。当用户 client 端进行远程调用时,可以通过简单的配置启用 request log 打印功能

场景描述

  1. 用户在调试服务时可能需要开启 access log。在使用 REST over servlet 通信方式的情况下,可以使用 web容器 的 access log 功能;而在使用 REST over Vertx 通信方式的情况下,可以使用 ServiceComb 提供的一套 access log 功能。

  2. 用户想要跟踪,记录客户端远程调用信息, 可以开启 request log。request log 同时支持记录 rest 和 highway 远程调用方式。

配置说明

启用 Access Log & Request Log

用户需要在 microservice.yaml 文件中增加配置以启用 access log 和 request log,配置示例如下:

  1. servicecomb:
  2. accesslog:
  3. enabled: true ## server 端 启用access log
  4. pattern: "%h - - %t %r %s %B %D" ## server 端 自定义 access log 日志格式
  5. request:
  6. enabled: true ## client 端开启 request log
  7. pattern: "%h %SCB-transport - - %t %r %s %D" ## client 端自定义 request log 日志格式

Access log & Request log 配置项说明

配置项取值范围默认值说明
servicecomb.accesslog.enabledtrue/falsefalse如果为true则启用access log,否则不启用
servicecomb.accesslog.pattern表示打印格式的字符串“%h - - %t %r %s %B %D”配置项见日志元素说明表
servicecomb.accesslog.request.enabledtrue/falsefalse如果为true则启用request log,否则不启用
servicecomb.accesslog.request.pattern表示打印格式的字符串“%h %SCB-transport - - %t %r %s %D”配置项见日志元素说明表

说明:

  • 以上四个配置项均可省略,若省略则使用默认值。

日志格式配置

目前可用的日志元素配置项见 日志元素说明表(Apache & W3C)日志元素说明表(ServiceComb)

日志元素说明表 (Apache & W3C)

元素名称Apache日志格式W3C日志格式说明
HTTP method%mcs-method-
HTTP status%ssc-status-
Duration in second%T--
Duration in millisecond%D--
Remote hostname%h--
Local hostname%v--
Local port%p--
Size of response%B-如果消息体长度为零则打印”0”
Size of response%b-如果消息体长度为零则打印”-“
First line of request%r-包含HTTP Method、Uri、Http版本三部分内容
URI path%Ucs-uri-stem-
Query string%qcs-uri-query-
URI path and query string-cs-uri-
Request protocol%H--
Datetime the request is received%t-按照默认设置打印时间戳,格式为”EEE, dd MMM yyyy HH:mm:ss zzz”,语言为英文,时区为GMT
Configurable datetime the request is received%{PATTERN}t-按照指定的格式打印时间戳,语言为英文,时区为GMT
Configurable datetime the request is received%{PATTERN|TIMEZONE|LOCALE}t-按照指定的格式、语言、时区打印时间戳。允许省略其中的某部分配置(但两个分隔符号”|”不可省略)。
Request header%{VARNAME}i-如果没有找到指定的header,则打印”-“
Response header%{VARNAME}o-如果没有找到指定的header,则打印”-“
Cookie%{VARNAME}C-如果没有找到指定的cookie,则打印”-“

日志元素说明表(ServiceComb)

ElementPlaceholderComment
TraceId%SCB-traceId打印ServiceComb生成的trace id,找不到则打印”-“
Invocation Context%{VARNAME}SCB-ctx打印key为VARNAME的invocation context值,找不到则打印”-“
Transport Method%SCB-transport打印当前调用的 transport methodrest 或者 highway

Access log 与 Request log 的日志元素对比

元素名称Apache&W3C日志格式access logaccess log 说明request logrequest log说明
HTTP method%m & cs-methodsupport-support-
HTTP status%s & sc-statussupport-support-
Duration in second%Tsupport-support-
Duration in millisecond%Dsupport-support-
Remote hostname%hsupport-support-
Local hostname%vsupport-support-
Local port%psupport-support-
Size of response%Bsupport如果消息体长度为零则打印”0”unsupported-
Size of response%bsupport如果消息体长度为零则打印”-“unsupported-
First line of request%rsupport包含HTTP Method、Uri、Http版本三部分内容support包含HTTP Method、Uri、Http版本三部分内容
URI path%U & cs-uri-stemsupport-support-
Query string%q & cs-uri-querysupport-support-
URI path and query stringcs-urisupport-support-
Request protocol%Hsupport-support-
Datetime of the request%tsupport收到请求的时间。默认格式为”EEE, dd MMM yyyy HH:mm:ss zzz”,语言为英文,时区为GMTsupport发送请求的时间。默认格式为”EEE, dd MMM yyyy HH:mm:ss zzz”,语言为英文,时区为GMT
Configurable datetime the request of the request%{PATTERN}tsupport收到请求的时间。按照指定的格式打印时间戳,语言为英文,时区为GMTsupport发送请求的时间。按照指定的格式打印时间戳,语言为英文,时区为GMT
Configurable datetime the request of the request%{PATTERN|TIMEZONE|LOCALE}tsupport收到请求的时间。按照指定的格式、语言、时区打印时间戳。允许省略其中的某部分配置(但两个分隔符号”|”不可省略)。support发送请求的时间。按照指定的格式、语言、时区打印时间戳。允许省略其中的某部分配置(但两个分隔符号”|”不可省略)。
Request header%{VARNAME}isupport如果没有找到指定的header,则打印”-“support如果没有找到指定的header,则打印”-“
Response header%{VARNAME}osupport如果没有找到指定的header,则打印”-“support如果没有找到指定的header,则打印”-“
Cookie%{VARNAME}Csupport如果没有找到指定的cookie,则打印”-“support如果没有找到指定的cookie,则打印”-“
TraceId%SCB-traceIdsupport打印ServiceComb生成的trace id,找不到则打印”-“support打印ServiceComb生成的trace id,找不到则打印”-“
Invocation Context%{VARNAME}SCB-ctxsupport打印key为VARNAME的invocation context值,找不到则打印”-“support打印key为VARNAME的invocation context值,找不到则打印”-“
transport method%SCB-transportunsupported只支持 rest 形式调用support调用使用的transport method

日志输出文件配置

Access log & Request log 的日志打印实现框架默认采用 Log4j ,并提供了一套默认的日志文件配置。用户可以在自己定义的 log4j.properties 文件中覆写这些配置。用户可配置的日志文件配置项见下表。

日志文件配置项

配置项默认值含义说明
paas.logs.accesslog.dir${paas.logs.dir}日志文件输出目录与普通日志输出到同一个目录中
paas.logs.accesslog.fileaccess.log日志文件名-
log4j.appender.access.MaxBackupIndex10最大保存的日志滚动文件个数-
log4j.appender.access.MaxFileSize20MB日志文件最大体积正在记录的文件达到此大小时触发日志滚动存储
log4j.appender.access.logPermissionrw———-日志文件权限-
paas.logs.requestlog.dir${paas.logs.dir}日志文件输出目录与普通日志输出到同一个目录中
paas.logs.requestlog.filerequest.log日志文件名-
log4j.appender.request.MaxBackupIndex10最大保存的日志滚动文件个数-
log4j.appender.request.MaxFileSize20MB日志文件最大体积正在记录的文件达到此大小时触发日志滚动存储
log4j.appender.request.logPermissionrw———-日志文件权限-

注意:
由于 ServiceComb 的日志打印功能只依赖 slf4j 的接口,因此用户可以选择其他日志打印框架,选择其他日志打印框架时需要用户自行配置日志文件输出选项。

日志实现框架切换为 logback

针对采用 logback 作为日志打印框架的项目,需要将日志打印框架依赖从 Log4j 改为 logback 并添加部分配置以使 log 功能正常生效。

1. 排除 Log4j 依赖

在将日志实现框架切换为 logback 之前,需要检查项目的依赖,从中排除掉 Log4j 相关的依赖项。在项目中运行 maven 命令 dependency:tree ,找出其中依赖了Log4j的ServiceComb组件,在其<dependency>依赖项中添加如下配置:

  1. <exclusion>
  2. <groupId>org.slf4j</groupId>
  3. <artifactId>slf4j-log4j12</artifactId>
  4. </exclusion>

2. 添加 logback 依赖

在 pom 文件中添加 logback 的依赖项:

  1. <dependency>
  2. <groupId>org.slf4j</groupId>
  3. <artifactId>slf4j-api</artifactId>
  4. </dependency>
  5. <dependency>
  6. <groupId>ch.qos.logback</groupId>
  7. <artifactId>logback-classic</artifactId>
  8. </dependency>
  9. <dependency>
  10. <groupId>ch.qos.logback</groupId>
  11. <artifactId>logback-core</artifactId>
  12. </dependency>

3. 配置 access log & request log 组件的 logger

ServiceComb 提供的日志打印组件是获取名为 accesslog & requestlog 的 logger 来打印 access log 和 request log ,因此将日志实现框架从 Log4j 切换为 logback 的关键就是提供一个名为 accesslog & requestlog 的 Logger,并为其配置好日志输出文件。以下是 access log & request log 在 logback 配置文件中的配置示例(本示例仅展示 access log & request log相关的配置,其他日志配置均省略):

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <configuration>
  3. <!-- 用户可根据需要自定义appender -->
  4. <appender name="ACCESSLOG" class="ch.qos.logback.core.rolling.RollingFileAppender">
  5. <file>./logs/access.log</file>
  6. <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
  7. <fileNamePattern>./logs/access-%d{yyyy-MM-dd}.log</fileNamePattern>
  8. </rollingPolicy>
  9. <!-- 注意:由于access log的内容是在代码中完成格式化的,因此这里只需输出message即可,无需添加额外的格式 -->
  10. <encoder>
  11. <pattern>%msg%n</pattern>
  12. </encoder>
  13. </appender>
  14. <appender name="REQUESTLOG" class="ch.qos.logback.core.rolling.RollingFileAppender">
  15. <file>./logs/request.log</file>
  16. <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
  17. <fileNamePattern>./logs/access-%d{yyyy-MM-dd}.log</fileNamePattern>
  18. </rollingPolicy>
  19. <!-- 注意:由于request log的内容是在代码中完成格式化的,因此这里只需输出message即可,无需添加额外的格式 -->
  20. <encoder>
  21. <pattern>%msg%n</pattern>
  22. </encoder>
  23. </appender>
  24. <!-- 提供一个名为"accesslog"的logger供access log打印组件使用 -->
  25. <logger name="accesslog" level="INFO" additivity="false">
  26. <appender-ref ref="ACCESSLOG" />
  27. </logger>
  28. <!-- 提供一个名为"requestlog"的logger供request log打印组件使用 -->
  29. <logger name="requestlog" level="INFO" additivity="false">
  30. <appender-ref ref="REQUESTLOG" />
  31. </logger>
  32. </configuration>

自定义扩展 Access Log & Request Log

用户可以利用 ServiceComb 提供的 AccessLogItem 扩展机制,定制自己的 AccessLogItem, 我们把 Request Log 也当做一种 Access Log。

相关类说明

  1. AccessLogItem
  1. public interface AccessLogItem<T> {
  2. // 从Server端获取信息,打印 Access Log 日志
  3. default void appendServerFormattedItem(ServerAccessLogEvent accessLogEvent, StringBuilder builder) {
  4. }
  5. // 从Client 端获取信息, 打印 Request Log
  6. default void appendClientFormattedItem(InvocationFinishEvent clientLogEvent, StringBuilder builder) {
  7. }
  8. }

AccessLogItem 的定义如上所示

  • Server 端 每收到一个请求,会触发一次 Access Log 日志打印。Client 端 每次对外远程调用结束,会触发一次 Request Log 日志打印。

  • 每次日志打印,SDK 都会遍历有效的 AccessLogItem ,调用对应的方法获取此 Item 生成的 Log片 段,并将全部片段拼接成一条 Log 打印到日志文件中。

  1. VertxRestAccessLogItemMeta
  1. // pattern占位符前缀
  2. protected String prefix;
  3. // pattern占位符后缀
  4. protected String suffix;
  5. // 优先级序号
  6. protected int order;
  7. // AccessLogItem构造器
  8. protected AccessLogItemCreator<RoutingContext> accessLogItemCreator;

VertxRestAccessLogItemMeta 包含如上属性,它定义了 ServiceComb 如何解析 pattern 字符串以获得特定的 AccessLogItem。

  • 如果用户想要定义一个占位符为 %user-definedAccessLogItem ,则需要声明一个 VertxRestAccessLogItemMeta 的子类,设置 prefix=”%user-defined”,suffix=null,当 AccessLogPatternParser 解析到 “%user-defined” 时,从此 meta 类中取得 AccessLogItemCreator 创建对应的 AccessLogItem注意:由于 “%user-defined” 占位符中没有变量部分,因此调用 AccessLogItemCreator 传入的配置参数为null。

  • 如果用户想要定义一个占位符为 %{VARNAME}user-definedAccessLogItem,则声明的 VertxRestAccessLogItemMeta 子类中,设置prefix=”%{“,suffix=”}user-defined”,当 AccessLogPatternParser 解析到 “%{VARNAME}user-defined”时,会截取出”VARNAME”作为配置参数传入AccessLogItemCreator,创建一个AccessLogItem

VertxRestAccessLogItemMeta 有一个子类 CompositeVertxRestAccessLogItemMeta,当用户需要定义多个 AccessLogItem 时,可以将多个 VertxRestAccessLogItemMeta 聚合到 CompositeVertxRestAccessLogItemMeta 中。Parser 加载到类型为 CompositeVertxRestAccessLogItemMeta 的AccessLogItemMeta时,会调用其 getAccessLogItemMetas() 方法获得一组 AccessLogItemMeta。VertxRestAccessLogItemMeta 使用SPI机制加载,而CompositeVertxRestAccessLogItemMeta可以让用户只在SPI配置文件中配置一条记录就加载多条meta信息,给了用户更灵活的选择。

  1. AccessLogItemCreator
  1. public interface AccessLogItemCreator<T> {
  2. // 接收配置值,返回一个AccessLogItem。如果AccessLogItem的占位符没有可变的配置值部分,则此方法会接收到null。
  3. AccessLogItem<T> createItem(String config);
  4. }

用户通过设置在自定义的 VertxRestAccessLogItemMeta 中的 AccessLogItemCreator 实例化自己的 AccessLogItem。由于这是一个函数式接口,当 AccessLogItem 的初始化方式较简单时,可以直接使用 Lambda表达式定义Creator,以简化开发。

AccessLogItemMeta 的匹配规则

AccessLogItemMeta 加载进 Parser 后,会进行一次排序。Parser 解析 pattern 串时会从前到后匹配 meta list,总的匹配规则如下:

  1. 优先匹配高优先级的meta。

  2. 优先匹配有后缀的meta,当匹配上多个有后缀meta时,取前后缀相距最小的一个。

  3. 优先匹配占位符长的meta,例如有两个 meta,”%abc”和”%a”,如果匹配中了”%abc”则直接返回,不再匹配”%a”。

示例说明

  1. 扩展自定义 AccessLogItem

首先用户需要 AccessLogItem 接口实现自己的 item:

  1. public class UserDefinedAccessLogItem implements AccessLogItem<RoutingContext> {
  2. private String config;
  3. public UserDefinedAccessLogItem(String config) {
  4. this.config = config;
  5. }
  6. @Override
  7. public void appendServerFormattedItem(ServerAccessLogEvent accessLogEvent, StringBuilder builder) {
  8. builder.append("user-defined--server-")
  9. .append(accessLogEvent.getRoutingContext().response().getStatusCode())
  10. .append("-")
  11. .append(config);
  12. }
  13. @Override
  14. public void appendClientFormattedItem(InvocationFinishEvent clientLogEvent, StringBuilder builder) {
  15. builder.append("user-server-defined-")
  16. .append(clientLogEvent.getResponse().getStatus())
  17. .append("-")
  18. .append(config);
  19. }
  20. }
  1. 定义 AccessLogItem 的 meta 类

继承 VertxRestAccessLogItemMetaCompositeVertxRestAccessLogItemMeta 类,定义AccessLogItem的前后缀等信息:

  1. public class UserDefinedCompositeExtendedAccessLogItemMeta extends CompositeVertxRestAccessLogItemMeta {
  2. private static final List<VertxRestAccessLogItemMeta> META_LIST = new ArrayList<>();
  3. static {
  4. META_LIST.add(new VertxRestAccessLogItemMeta("%{", "}user-defined", UserDefinedAccessLogItem::new));
  5. }
  6. @Override
  7. public List<VertxRestAccessLogItemMeta> getAccessLogItemMetas() {
  8. return META_LIST;
  9. }
  10. }
  1. 配置SPI加载文件

resources/META-INF/services/ 目录下定义一个名为 “org.apache.servicecomb.transport.rest.vertx.accesslog.parser.VertxRestAccessLogItemMeta” 的文件,将上一步中定义的meta类完整类名填写到该文件中,供Parser加载meta类。

  1. 配置 Access Log 的 pattern
  1. # 服务端配置
  2. servicecomb:
  3. accesslog:
  4. enabled: true ## 应用作为服务端,开启 Access log
  5. pattern: "%{param}user-defined" ## Access log 日志格式
  6. request:
  7. enabled: true ## 应用作为客户端,开启 Request log
  8. pattern: "%{param}user-defined" ## Request log 日志格式

以服务端为例, 运行服务触发Access Log打印,假设请求返回状态码是 200,则可以看到Access Log打印内容为 “user-defined--server-200-param“。

示例代码

microservice.yaml文件中的配置

  1. ## other configurations omitted
  2. servicecomb:
  3. accesslog:
  4. enabled: true ## 应用作为服务端,开启 Access log
  5. pattern: "%h - - %t %r %s %B %D" ## Access log 日志格式
  6. request:
  7. enabled: true ## 应用作为客户端,开启 Request log
  8. pattern: "%h %SCB-transport - - %t %r %s %D" ## Request log 日志格式

log4j.properties文件中的配置

  1. # log configuration item
  2. paas.logs.dir=../logs/
  3. paas.logs.accesslog.file=access.log
  4. paas.logs.requestlog.file=request.log
  5. # access log File appender
  6. log4j.appender.access.MaxBackupIndex=10
  7. log4j.appender.access.MaxFileSize=20MB
  8. log4j.appender.access.logPermission=rw-------
  9. # request log File appender
  10. log4j.appender.request.MaxBackupIndex=10
  11. log4j.appender.request.MaxFileSize=20MB
  12. log4j.appender.request.logPermission=rw-------