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_PROJECT
和GOOGLE_APPLICATION_CREDENTIALS
环境变量分别设置为项目 ID 和凭据私钥位置。如果您分别使用Google Cloud SDK,gcloud 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-context
Headers 下包含跟踪 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_NAME
和STACKDRIVER_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>
如果要对日志输出进行更多控制,则可以进一步配置附加程序。可以使用以下属性:
Property | Default Value | Description |
---|---|---|
log | spring.log | Stackdriver 日志名称。也可以通过STACKDRIVER_LOG_NAME 环境变量进行设置。 |
flushLevel | WARN | 如果遇到具有此级别的日志条目,请触发将本地缓冲的日志刷新到 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 将正确设置。
如果要对日志输出进行更多控制,则可以进一步配置附加程序。可以使用以下属性:
Property | Default Value | Description |
---|---|---|
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 而没有完全限定的格式。 | |
includeTraceId | true | 应该包含traceId |
includeSpanId | true | 应该包含spanId |
includeLevel | true | 是否应包括严重性 |
includeThreadName | true | 是否应包含线程名称 |
includeMDC | true | 应包括所有 MDC 属性。 Spring Sleuth 提供的 MDC 属性X-B3-TraceId ,X-B3-SpanId 和X-Span-Export 将被排除,因为它们将分别处理 |
includeLoggerName | true | 应包括 Logger 的名称 |
includeFormattedMessage | true | 是否应包括格式化的日志消息。 |
includeExceptionInMessage | true | 应将堆栈跟踪附加到格式化的日志消息中。仅当includeFormattedMessage 为true 时才评估此设置。 |
includeContextName | true | 是否应包含日志记录上下文 |
includeMessage | false | 应包含空白占位符的日志消息 |
includeException | false | 应该将堆栈跟踪作为自己的字段包括在内 |
这是这种 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。