9. Stackdriver Logging Support

Maven coordinates, using Spring Cloud GCP BOM:

<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 is the managed logging service provided by Google Cloud Platform.

This module provides support for associating a web request trace ID with the corresponding log entries. This allows grouping of log messages by request.

[Note]Note

Due to the way logging is set up, the GCP project ID and credentials defined in application.properties are ignored. Instead, you should set the GOOGLE_CLOUD_PROJECT and GOOGLE_APPLICATION_CREDENTIALS environment variables to the project ID and credentials private key location, respectively.

TraceIdLoggingWebMvcInterceptor extracts the request trace ID from an HTTP request using a TraceIdExtractor and stores it in a thread-local of the TraceLoggingEnhancer which can then be used in a logging appender to add the trace ID metadata to log messages.

There are implementations provided for TraceIdExtractor:

ExtractorDescription

XCloudTraceIdExtractor

Checks the X-Cloud-Trace-Context HTTP header that is automatically added to HTTP requests sent to applications hosted on GCP services such as App Engine and GKE

ZipkinTraceIdExtractor

Checks the X-B3-TraceId header

CompositeTraceIdExtractor

Instantiated with a list of other TraceIdExtractor, and provides the first trace ID found using these extractors in the given order

LoggingWebMvcConfigurer configuration class is also provided to help register the TraceIdLoggingWebMvcInterceptor in Spring MVC applications.

Currently, Java Util Logging (JUL) and Logback are supported.

9.1 Logback Support

There are 2 possibilities to log to Stackdriver via this library with Logback:

9.1.1 Log via API

For Logback, a org/springframework/cloud/gcp/autoconfigure/logging/logback-appender.xml file is made available for import to make it easier to configure the Logback appender.

Your configuration may then look something like this:

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

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

STACKDRIVER_LOG_NAME and STACKDRIVER_LOG_FLUSH_LEVEL environment variables can be used to customize the STACKDRIVER appender.

Also see the spring-cloud-gcp-starter-logging module.

9.1.2 Log via Console

If you run your Spring Boot application in a Kubernetes cluster in the Google Cloud (GKE) or on App Engine flexible environment, you can log JSON directly from the console by including org/springframework/cloud/gcp/logging/logback-json-appender.xml. The traceId will be set correctly.

You need the additional dependency:

<dependency>
  <groupId>ch.qos.logback.contrib</groupId>
  <artifactId>logback-json-classic</artifactId>
  <version>0.1.5</version>
</dependency>

Your Logback configuration may then look something like this:

<configuration>
  <property name="projectId" value="test-project"/>
  <include resource="org/springframework/cloud/gcp/logging/logback-json-appender.xml" />

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

If you want to have more control over the log output, you can also configure the ConsoleAppender yourself. The following properties are available:

PropertyDefault ValueDescription

projectId

 

Only required for logging the correct traceId: projects/[PROJECT-ID]/traces/[TRACE-ID]. If projectId is not set, the logged traceId will match the one provided by spring-cloud-gpc-trace

includeTraceId

true

Should the traceId be included

includeSpanId

true

Should the spanId be included

includeLevel

true

Should the severity be included

includeThreadName

true

Should the thread name be included

includeMDC

true

Should all MDC properties be included. The MDC properties X-B3-TraceId, X-B3-SpanId and X-Span-Export provided by Spring Sleuth will get excluded as they get handled separately

includeLoggerName

true

Should the name of the logger be included

includeFormattedMessage

true

Should the formatted log message be included.

includeExceptionInMessage

true

Should the stacktrace be appended to the formatted log message. This setting is only evaluated if includeFormattedMessage is true

includeContextName

true

Should the logging context be included

includeMessage

false

Should the log message with blank placeholders be included

includeException

false

Should the stacktrace be included as a own field

This is an example of such an Logback configuration:

<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>