Google Stackdriver Logging Client for Java
Java idiomatic client for Stackdriver 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>4.1.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 BOM, add this to your dependencies:
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>google-cloud-logging</artifactId>
<version>1.100.0</version>
</dependency>
If you are using Gradle, add this to your dependencies
compile 'com.google.cloud:google-cloud-logging:1.100.0'
If you are using SBT, add this to your dependencies
libraryDependencies += "com.google.cloud" % "google-cloud-logging" % "1.100.0"
Authentication
See the Authentication section in the base directory's README.
Getting Started
Prerequisites
You will need a Google Cloud Platform Console project with the Stackdriver Logging API enabled.
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 SDK 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 Stackdriver Logging
Stackdriver 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 Stackdriver Logging client library docs to learn how to use this Stackdriver Logging Client Library.
Creating an authorized service object
To make authenticated requests to Stackdriver Logging, you must create a service object with credentials. You can then make API calls by calling methods on the Logging service object. The simplest way to authenticate is to use Application Default Credentials. These credentials are automatically inferred from your environment, so 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 authentication options, see the Authentication page.
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
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));
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.cloud.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"));
Iterator<LogEntry> entryIterator = entries.iterateAll().iterator();
while (entryIterator.hasNext()) {
System.out.println(entryIterator.next());
}
Add a Stackdriver Logging handler to a logger
You can also register a LoggingHandler
to a java.util.logging.Logger
that publishes log entries
to Stackdriver 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 Stackdriver 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
Complete source code
In CreateAndListMetrics.java, WriteAndListLogEntries.java and AddLoggingHandler.java we put together all the code shown above into three programs. The programs assume that you are running on Compute Engine or from your own desktop.
Troubleshooting
To get help, follow the instructions in the shared Troubleshooting document.
Transport
Stackdriver Logging uses gRPC for the transport layer.
Java Versions
Java 7 or above is required for using this client.
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 7 | |
Java 8 | |
Java 8 OSX | |
Java 8 Windows | |
Java 11 |