157. Stackdriver Logging

使用 Spring Cloud GCP BOM 进行 Maven 坐标:

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-gcp-starter-logging</artifactId>
</dependency>

Gradle coordinates:

dependencies {
    compile group: 'org.springframework.cloud', name: 'spring-cloud-gcp-starter-logging'
}

Stackdriver Logging是 Google Cloud Platform 提供的托管日志记录服务。

该模块提供了将 Web 请求跟踪 ID 与相应的日志条目相关联的支持。通过从Map 诊断上下文(MDC)检索X-B3-TraceId值来实现,该值由 Spring Cloud Sleuth 设置。如果未使用 Spring Cloud Sleuth,则配置的TraceIdExtractor将提取所需的 Headers 值并将其设置为日志条目的跟踪 ID。这允许根据请求将日志消息分组,例如在Google Cloud Console 日志查看器中。

Note

由于设置了日志记录方式,因此忽略了application.properties中定义的 GCP 项目 ID 和凭据。而是应将GOOGLE_CLOUD_PROJECTGOOGLE_APPLICATION_CREDENTIALS环境变量分别设置为项目 ID 和凭据私钥位置。如果您分别使用Google Cloud SDKgcloud config set project [YOUR_PROJECT_ID]gcloud auth application-default login命令,则可以轻松完成此操作。

157.1 Web MVC 拦截器

为了在基于 Web MVC 的应用程序中使用,提供了TraceIdLoggingWebMvcInterceptor,可以使用TraceIdExtractor从 HTTP 请求中提取请求跟踪 ID,并将其存储在本地线程中,然后可以在日志记录附加程序中使用该跟踪 ID 将跟踪 ID 元数据添加到日志消息。

Warning

如果启用了 Spring Cloud GCP 跟踪,则日志记录模块将禁用自身并将日志相关性委派给 Spring Cloud Sleuth。

还提供LoggingWebMvcConfigurer配置类,以帮助在 Spring MVC 应用程序中注册TraceIdLoggingWebMvcInterceptor

Google Cloud Platform 上托管的应用程序在x-cloud-trace-contextHeaders 下包含跟踪 ID,这些 ID 将包含在日志条目中。但是,如果使用 Sleuth,则会从 MDC 中获取跟踪 ID。

157.2 登录支持

当前,仅支持 Logback,并且有两种通过 Logback 通过此库通过 Logback 登录到 Stackdriver 的可能性:通过直接 API 调用和通过 JSON 格式的控制台日志。

157.2.1 通过 API 登录

使用org/springframework/cloud/gcp/autoconfigure/logging/logback-appender.xml可使用 Stackdriver 附加程序。此附加程序从 JUL 或 Logback 日志条目构建 Stackdriver Logging 日志条目,向其添加跟踪 ID,然后将其发送到 Stackdriver Logging。

STACKDRIVER_LOG_NAMESTACKDRIVER_LOG_FLUSH_LEVEL环境变量可用于自定义STACKDRIVER附加程序。

然后,您的配置可能如下所示:

<configuration>
  <include resource="org/springframework/cloud/gcp/autoconfigure/logging/logback-appender.xml" />

  <root level="INFO">
    <appender-ref ref="STACKDRIVER" />
  </root>
</configuration>

如果要对日志输出进行更多控制,则可以进一步配置附加程序。可以使用以下属性:

PropertyDefault ValueDescription
logspring.logStackdriver 日志名称。也可以通过STACKDRIVER_LOG_NAME环境变量进行设置。
flushLevelWARN如果遇到具有此级别的日志条目,请触发将本地缓冲的日志刷新到 Stackdriver Logging。也可以通过STACKDRIVER_LOG_FLUSH_LEVEL环境变量进行设置。

157.2.2 通过控制台登录

对于 Logback,使org/springframework/cloud/gcp/autoconfigure/logging/logback-json-appender.xml文件可用于导入,以使其更易于配置 JSON Logback 附加程序。

然后,您的配置可能如下所示:

<configuration>
  <include resource="org/springframework/cloud/gcp/autoconfigure/logging/logback-json-appender.xml" />

  <root level="INFO">
    <appender-ref ref="CONSOLE_JSON" />
  </root>
</configuration>

如果您的应用程序在 Google Kubernetes Engine,Google Compute Engine 或 Google App Engine Flexible 上运行,则您的控制台日志将自动保存到 Google Stackdriver Logging。因此,您只需在日志记录配置中包含org/springframework/cloud/gcp/autoconfigure/logging/logback-json-appender.xml即可,它将 JSON 条目记录到控制台。跟踪 ID 将正确设置。

如果要对日志输出进行更多控制,则可以进一步配置附加程序。可以使用以下属性:

PropertyDefault ValueDescription
projectId如果未设置,则按以下 Sequences 确定默认值:

SPRING_CLOUD_GCP_LOGGING_PROJECT_ID环境变量。
DefaultGcpProjectIdProvider.getProjectId()
用于生成标准的 Stackdriver Trace ID 格式:projects/[PROJECT-ID]/traces/[TRACE-ID]
需要此格式才能在 Stackdriver Trace 和 Stackdriver Logging 之间关联跟踪。
如果未设置projectId且无法确定projectId,则它将记录traceId而没有完全限定的格式。
includeTraceIdtrue应该包含traceId
includeSpanIdtrue应该包含spanId
includeLeveltrue是否应包括严重性
includeThreadNametrue是否应包含线程名称
includeMDCtrue应包括所有 MDC 属性。 Spring Sleuth 提供的 MDC 属性X-B3-TraceIdX-B3-SpanIdX-Span-Export将被排除,因为它们将分别处理
includeLoggerNametrue应包括 Logger 的名称
includeFormattedMessagetrue是否应包括格式化的日志消息。
includeExceptionInMessagetrue应将堆栈跟踪附加到格式化的日志消息中。仅当includeFormattedMessagetrue时才评估此设置。
includeContextNametrue是否应包含日志记录上下文
includeMessagefalse应包含空白占位符的日志消息
includeExceptionfalse应该将堆栈跟踪作为自己的字段包括在内

这是这种 Logback 配置的示例:

<configuration >
  <property name="projectId" value="${projectId:-${GOOGLE_CLOUD_PROJECT}}"/>

  <appender name="CONSOLE_JSON" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
      <layout class="org.springframework.cloud.gcp.logging.StackdriverJsonLayout">
        <projectId>${projectId}</projectId>

        <!--<includeTraceId>true</includeTraceId>-->
        <!--<includeSpanId>true</includeSpanId>-->
        <!--<includeLevel>true</includeLevel>-->
        <!--<includeThreadName>true</includeThreadName>-->
        <!--<includeMDC>true</includeMDC>-->
        <!--<includeLoggerName>true</includeLoggerName>-->
        <!--<includeFormattedMessage>true</includeFormattedMessage>-->
        <!--<includeExceptionInMessage>true</includeExceptionInMessage>-->
        <!--<includeContextName>true</includeContextName>-->
        <!--<includeMessage>false</includeMessage>-->
        <!--<includeException>false</includeException>-->
      </layout>
    </encoder>
  </appender>
</configuration>

157.3 Sample

提供了Spring Boot 应用程序 samples,以显示如何使用 Cloud Logging Starter。