gRPC.md

Getting started with gRPC

First remove any preexisting log configuration (i.e. logback.xml) and so on.

Then import the cloud-logging BOM:

Maven BOM coordinates

Add

<cloud-logging.version>4.0.x</cloud-logging>

and

<dependency>
    <groupId>no.entur.logging.cloud</groupId>
    <artifactId>bom</artifactId>
    <version>${cloud-logging.version}</version>
    <type>pom</type>
    <scope>import</scope>    
</dependency>

or

Gradle BOM coordinates

For

ext {
   cloudLoggingVersion = '4.0.x'
}

add

implementation platform("no.entur.logging.cloud:bom:${cloudLoggingVersion}")
testImplementation platform("no.entur.logging.cloud:bom:${cloudLoggingVersion}")

Spring Boot starter

Add the spring-boot-starter artifact coordinates to your project.

Maven Spring Boot Starter coordinates

<dependency>
    <groupId>no.entur.logging.cloud</groupId>
    <artifactId>spring-boot-starter-gcp-grpc-ecosystem</artifactId>
</dependency>
<dependency>
    <groupId>no.entur.logging.cloud</groupId>
    <artifactId>spring-boot-starter-gcp-grpc-ecosystem-test</artifactId>
    <scope>test</scope>
</dependency>

or

Gradle Spring Boot Starter coordinates

implementation ("no.entur.logging.cloud:spring-boot-starter-gcp-grpc-ecosystem")
testImplementation ("no.entur.logging.cloud:spring-boot-starter-gcp-grpc-ecosystem-test")

Verify configuration by toggling between output modes in a unit test:

try (Closeable c = CompositeConsoleOutputControl.useHumanReadableJsonEncoder()) {
    // your logging here
}

For additional error levels, try the DevOpsLogger:

DevOpsLogger LOGGER = DevOpsLoggerFactory.getLogger(MyClass.class);

// ... your code here

LOGGER.errorTellMeTomorrow("Error statement");
LOGGER.errorInterruptMyDinner("Critical statement");
LOGGER.errorWakeMeUpRightNow("Alert statement");

Configure log levels via Spring, i.e. application.properties like

logging.level.root=INFO
logging.level.my.package=WARN

Request-response logging

Import the request-response Spring Boot starters:

Maven Spring Boot Starter coordinates

<dependency>
    <groupId>no.entur.logging.cloud</groupId>
    <artifactId>request-response-spring-boot-starter-gcp-grpc-ecosystem</artifactId>
</dependency>
<dependency>
    <groupId>no.entur.logging.cloud</groupId>
    <artifactId>request-response-spring-boot-starter-gcp-grpc-ecosystem-test</artifactId>
    <scope>test</scope>
</dependency>

or

Gradle Spring Boot Starter coordinates

implementation ("no.entur.logging.cloud:request-response-spring-boot-starter-gcp-grpc-ecosystem")
testImplementation ("no.entur.logging.cloud:request-response-spring-boot-starter-gcp-grpc-ecosystem-test")

Adjust the logger using

entur.logging.request-response.logger.level=INFO
entur.logging.request-response.logger.name=no.entur.logging.cloud

Set OrderedGrpcLoggingServerInterceptor order using

entur.logging.request-response.grpc.server.interceptor-order=0

also add RequestResponseGRpcExceptionHandlerInterceptor error handler before the response logging, so that the response status is logged correctly

entur.logging.request-response.grpc.server.exception-handler.interceptor-order=0

Optionally also configure the OrderedGrpcLoggingClientInterceptor order using

entur.logging.request-response.grpc.client.interceptor-order=0

Also create your own beans for

• JsonFormat.TypeRegistry
• GrpcStatusMapper
• GrpcPayloadJsonMapper
• GrpcMetadataJsonMapper
• GrpcClientLoggingFilters

to further customize logging.

On-demand logging

This feature adjusts the log level for individual web server requests, taking into account actual behaviour.

• increase log level for happy-cases (i.e. WARN or ERROR), otherwise
• reduce log level (i.e. INFO) for
  • unexpected HTTP response codes
  • unexpected log statement levels (i.e. ERROR)
  • unexpectedly long call duration
  • troubleshooting

Import the on-demand Spring Boot starters:

Maven Spring Boot Starter coordinates

<dependency>
    <groupId>no.entur.logging.cloud</groupId>
    <artifactId>on-demand-spring-boot-starter-gcp-grpc</artifactId>
</dependency>

or

Gradle Spring Boot Starter coordinates

implementation ("no.entur.logging.cloud:on-demand-spring-boot-starter-gcp-grpc")

While disabled by default, on-demand logging can be enabled using

entur.logging.grpc.ondemand.enabled=true

Add the GrpcLoggingScopeContextInterceptor interceptor to your gRPC services.

Running applications locally

For 'classic' one-line log output when running a server locally, additionally add the logging test artifacts to the main scope during local execution only.

• Maven: Use profiles
• Gradle:
  • Use configurations, and/or
  • add dependencies directly to task

Gradle bootRun example

tasks.register("logPlainly") {
   dependencies {
      implementation("no.entur.logging.cloud:request-response-spring-boot-starter-gcp-grpc-ecosystem-test")
      implementation("no.entur.logging.cloud:spring-boot-starter-gcp-grpc-ecosystem-test")
   }
}

tasks.withType(JavaExec).configureEach {
   dependsOn("logPlainly")
}

Then configure desired output by specifying entur.logging.style

entur.logging.style=humanReadablePlain|humanReadableJson|machineReadableJson

Opting out

Some included features can be removed by excluding the corresponding artifacts:

• micrometer
  • micrometer
  • micrometer-gcp
• correlation id trace
  • correlation-id-trace-spring-boot-grpc

Running applications locally

For 'classic' one-line log output when running a server locally, additionally add the logging test artifacts to the main scope during local execution only.

• Maven: Use profiles
• Gradle:
  • Use configurations, and/or
  • add dependencies directly to task

Gradle bootRun example

tasks.register("logPlainly") {
   dependencies {
      implementation("no.entur.logging.cloud:request-response-spring-boot-starter-gcp-web-test")
      implementation("no.entur.logging.cloud:spring-boot-starter-gcp-web-test")
   }
}

tasks.withType(JavaExec).configureEach {
   dependsOn("logPlainly")
}

Then configure desired output by specifying entur.logging.style

entur.logging.style=humanReadablePlain|humanReadableJson|machineReadableJson

Troubleshooting

request-response logging not working

Did you import the relevant artifacts?

on-demand logging not working

Did you import the relevant artifacts?

Set property to enable.