Awesome

Google Cloud Logging Client for Java

Java idiomatic client for Cloud Logging.

Quickstart

If you are using Maven with BOM, add this to your pom.xml file:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.43.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-logging</artifactId>
  </dependency>

</dependencies>

If you are using Maven without the BOM, add this to your dependencies:

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging</artifactId>
  <version>3.17.2</version>
</dependency>

If you are using Gradle 5.x or later, add this to your dependencies:

implementation platform('com.google.cloud:libraries-bom:26.50.0')

implementation 'com.google.cloud:google-cloud-logging'

If you are using Gradle without BOM, add this to your dependencies:

implementation 'com.google.cloud:google-cloud-logging:3.20.7'

If you are using SBT, add this to your dependencies:

libraryDependencies += "com.google.cloud" % "google-cloud-logging" % "3.20.7"

Authentication

See the Authentication section in the base directory's README.

Authorization

The client application making API calls must be granted authorization scopes required for the desired Cloud Logging APIs, and the authenticated principal must have the IAM role(s) required to access GCP resources using the Cloud Logging API calls.

Getting Started

Prerequisites

You will need a Google Cloud Platform Console project with the Cloud Logging API enabled. You will need to enable billing to use Google Cloud Logging. Follow these instructions to get your project set up. You will also need to set up the local development environment by installing the Google Cloud Command Line Interface and running the following commands in command line: gcloud auth login and gcloud config set project [YOUR PROJECT ID].

Installation and setup

You'll need to obtain the google-cloud-logging library. See the Quickstart section to add google-cloud-logging as a dependency in your code.

About Cloud Logging

Cloud Logging allows you to store, search, analyze, monitor, and alert on log data and events from Google Cloud and Amazon Web Services. Using the BindPlane service, you can also collect this data from over 150 common application components, on-premises systems, and hybrid cloud systems. BindPlane is included with your Google Cloud project at no additional cost.

See the Cloud Logging client library docs to learn how to use this Cloud Logging Client Library.

Creating an authorized service object

To make requests to Cloud Logging, you must create a service object with valid credentials. You can then make API calls by calling methods on the Logging service object. You can obtain credentials by using Application Default Credentials. Or you can use a Service Account which is a recommended way to obtain credentials. The credentials can be automatically inferred from your environment. Then you only need the following code to create your service object:

import com.google.cloud.logging.Logging;
import com.google.cloud.logging.LoggingOptions;

LoggingOptions options = LoggingOptions.getDefaultInstance();
try(Logging logging = options.getService()) {
  // use logging here
}

For other options, see the Authentication page. The service object should be granted permissions to make API calls. Each API call describes the permissions under Authorized Scopes section. See Logging API to find the required list of permissions or consult with Access control guide for predefined IAM roles that can be granted to the Logging service object.

Creating a metric

With Logging you can create logs-based metrics. Logs-based metrics allow to keep track of the number of log messages associated to specific events. Add the following imports at the top of your file:

import com.google.cloud.logging.Metric;
import com.google.cloud.logging.MetricInfo;

Then, to create the metric, use the following code:

MetricInfo metricInfo = MetricInfo.newBuilder("test-metric", "severity >= ERROR")
    .setDescription("Log entries with severity higher or equal to ERROR")
    .build();
logging.create(metricInfo);

Writing log entries

For an interactive tutorial click

With Logging you can also write custom log entries. Add the following imports at the top of your file:

import com.google.cloud.MonitoredResource;
import com.google.cloud.logging.LogEntry;
import com.google.cloud.logging.Logging;
import com.google.cloud.logging.Payload.StringPayload;

import java.util.Collections;

Then, to write the log entries, use the following code:

LogEntry firstEntry = LogEntry.newBuilder(StringPayload.of("message"))
    .setLogName("test-log")
    .setResource(MonitoredResource.newBuilder("global")
        .addLabel("project_id", options.getProjectId())
        .build())
    .build();
logging.write(Collections.singleton(firstEntry));

The library supports writing log entries synchronously and asynchronously. In the synchronous mode each call to write() method results in a consequent call to Logging API to write a log entry. In the asynchronous mode the call(s) to Logging API takes place asynchronously and few calls to write() method may be batched together to compose a single call to Logging API. The default mode of writing is asynchronous. It can be configured in the java.util.logging handler configuration file:

com.google.cloud.logging.LoggingHandler.synchronicity=SYNC

or in the code after initiating an instance of Logging by calling:

logging.setWriteSynchronicity(Synchronicity.SYNC);

NOTE:

Writing log entries asynchronously in some Google Cloud managed environments (e.g. Cloud Functions) may lead to unexpected results such as absense of expected log entries or abnormal program execution. To avoid these unexpected results, it is recommended to use synchronous mode.

Controlling the batching settings

As mentioned before, in the asynchronous mode the call(s) to Logging API takes place asynchronously and few calls to write() method may be batched together to compose a single call to Logging API. In order to control the batching settings, the LoggingOptions is enhanced with BatchingSettings which can be set as shown in example below:

import com.google.api.gax.batching.BatchingSettings;
import com.google.api.gax.batching.FlowControlSettings;
import com.google.api.gax.batching.FlowController;

LoggingOptions actual =
    LoggingOptions.newBuilder()
        .setBatchingSettings(
            BatchingSettings.newBuilder()
                .setIsEnabled(true)
                .setElementCountThreshold(1000L)
                .setRequestByteThreshold(1048576L)
                .setDelayThreshold(Duration.ofMillis(50L))
                .setFlowControlSettings(
                    FlowControlSettings.newBuilder()
                        .setMaxOutstandingElementCount(100000L)
                        .setMaxOutstandingRequestBytes(10485760L)
                        .setLimitExceededBehavior(
                            FlowController.LimitExceededBehavior.ThrowException)
                        .build())
                .build())
        .setProjectId('Your project ID')
        .build();

You can find more information about batching parameters see BatchingSettings.

Listing log entries

With Logging you can also list log entries that have been previously written. Add the following imports at the top of your file:

import com.google.api.gax.paging.Page;
import com.google.cloud.logging.LogEntry;
import com.google.cloud.logging.Logging.EntryListOption;

Then, to list the log entries, use the following code:

Page<LogEntry> entries = logging.listLogEntries(
    EntryListOption.filter("logName=projects/" + options.getProjectId() + "/logs/test-log"));
while (entries != null) {
  for (LogEntry logEntry : entries.iterateAll()) {
    System.out.println(logEntry);
  }
  entries = entries.getNextPage();
}

Add a Cloud Logging handler to a logger

You can also register a LoggingHandler to a java.util.logging.Logger that publishes log entries to Cloud Logging. Given the following logger:

private final static Logger LOGGER = Logger.getLogger(MyClass.class.getName());

You can register a LoggingHandler with the code:

LoggingHandler.addHandler(LOGGER, new LoggingHandler());

After that, logs generated using LOGGER will be also directed to Cloud Logging.

Notice that you can also register a LoggingHandler via the logging.properties configuration file. Adding, for instance, the following line:

com.google.cloud.examples.logging.snippets.AddLoggingHandler.handlers=com.google.cloud.logging.LoggingHandler

Alternative way to ingest logs in Google Cloud managed environments

If you use Java logger with the Cloud Logging Handler, you can configure the handler to output logs to stdout using the structured logging Json format. To do this, add com.google.cloud.logging.LoggingHandler.redirectToStdout=true to the logger configuration file. You can use this configuration when running applications in Google Cloud managed environments such as AppEngine, Cloud Run, Cloud Function or GKE. The logger agent installed on these environments can capture STDOUT and ingest it into Cloud Logging. The agent can parse structured logs printed to STDOUT and capture additional log metadata beside the log payload. The parsed information includes severity, source location, user labels, http request and tracing information.

Auto-population of log entrys' metadata

LogEntry object metadata information such as monitored resource, Http request or source location are automatically populated with information that the library retrieves from the execution context. The library populates only empty (set to null) LogEntry fields. This behavior in the Logging instance can be opted out via LoggingOptions. Call LoggingOptions.Builder.setAutoPopulateMetadata(false) to configure logging options to opt-out the metadata auto-population. Cloud Logging handler can be configured to opt-out automatic population of the metadata using the logger configuration. To disable the metadata auto-population add com.google.cloud.logging.LoggingHandler.autoPopulateMetadata=false to the logger configuration file.

The auto-population logic populates source location only for log entries with Severity.DEBUG severity. The execution context of the Http request and tracing information is maintained by ContextHandler class. The context is managed in the scope of the thread. If you do not use thread pools for multi-threading the ContextHandler can be configured to propagate the context to the scope of the child threads. To enable this add com.google.cloud.logging.ContextHandler.useInheritedContext=true to the logger configuration file. The library provides two methods to update the context:

Manually set the context. You can use the following methods of the Context.Builder to set the context information. Use the method setRequest() to setup the HttpRequest instance or setRequestUrl(), setRequestMethod(), setReferer() , setRemoteIp() and setServerIp() to setup the fields of the HttpRequest. The trace and span Ids can be set directly using setTraceId() and setSpanId() respectively. Alternatively it can be parsed from the W3C tracing context header using loadW3CTraceParentContext() or from the Google Cloud tracing context header using loadCloudTraceContext().
```
Context context = Context.newBuilder().setHttpRequest(request).setTrace(traceId).setSpanId(spanId).build();
(new ContextHandler()).setCurrentContext(context);
```
Using servlet initializer. If your application uses a Web server based on Jakarta servlets (e.g. Jetty or Tomcat), you can add the servlet initializer package to your WAR. The package implements a service provider interface (SPI) for javax.servlet.ServletContainerInitializer and filters all servlet requests to automatically capture the execution context of the servlet request and store it using ContextHandler class. The stored Context class instances are used to populate Http request and tracing information. If you use Maven, to use the servlet initializer add the following dependency to your BOM:
```
<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-logging-servlet-initializer</artifactId>
</dependency>      
```

Population of Trace/Span ID fields in a LogEntry

Cloud Logging libraries use trace fields within LogEntry to capture trace contexts, which enables the correlation of logs and traces, and distributed tracing troubleshooting. These tracing fields, including trace, spanId, and traceSampled, define the trace context for a LogEntry.

Tracing information set manually takes precedence over information set by the following methods:

Auto-populate Trace/Span ID from OpenTelemetry Context If you are using OpenTelemetry and there is an active span in the OpenTelemetry Context, the trace, span_id, and trace_sampled fields in the log entry are populated from the active span. More information about OpenTelemetry can be found here.
Use the servlet initializer to Populate Trace/Span ID from HTTP Headers If trace/span Id are not manually set or auto-populated from OpenTelemetry context, you can use the servlet initializer to populate trace/span Id from HTTP headers. This package filters all servlet requests to automatically capture the execution context of the servlet request and stores it by using ContextHandler class. Http request and trace/span Id information are populated from the stored Context class instances.
Using this method, trace/span Id can be automatically populated from either the W3C Traceparent or X-Cloud-Trace-Context headers.

Samples

Samples are in the samples/ directory.

Sample	Source Code	Try it
Native Image Logging Sample	source code
Get Sink Metadata	source code
List Log Entries	source code
List Logs	source code
Log Entry Write Http Request	source code
Quickstart Sample	source code
Tail Log Entries	source code
Write Log Entry	source code
Quickstart	source code
Example Enhancer	source code

Troubleshooting

To get help, follow the instructions in the shared Troubleshooting document.

Transport

Cloud Logging uses gRPC for the transport layer.

Supported Java Versions

Java 8 or above is required for using this client.

Google's Java client libraries, Google Cloud Client Libraries and Google Cloud API Libraries, follow the Oracle Java SE support roadmap (see the Oracle Java SE Product Releases section).

For new development

In general, new feature development occurs with support for the lowest Java LTS version covered by Oracle's Premier Support (which typically lasts 5 years from initial General Availability). If the minimum required JVM for a given library is changed, it is accompanied by a semver major release.

Java 11 and (in September 2021) Java 17 are the best choices for new development.

Keeping production systems current

Google tests its client libraries with all current LTS versions covered by Oracle's Extended Support (which typically lasts 8 years from initial General Availability).

Legacy support

Google's client libraries support legacy versions of Java runtimes with long term stable libraries that don't receive feature updates on a best efforts basis as it may not be possible to backport all patches.

Google provides updates on a best efforts basis to apps that continue to use Java 7, though apps might need to upgrade to current versions of the library that supports their JVM.

Where to find specific information

The latest versions and the supported Java versions are identified on the individual GitHub repository github.com/GoogleAPIs/java-SERVICENAME and on google-cloud-java.

Versioning

This library follows Semantic Versioning.

Contributing

Contributions to this library are always welcome and highly encouraged.

See CONTRIBUTING for more information how to get started.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Code of Conduct for more information.

License

Apache 2.0 - See LICENSE for more information.

CI Status

Java Version	Status
Java 8
Java 8 OSX
Java 8 Windows
Java 11

Java is a registered trademark of Oracle and/or its affiliates.