diff --git a/README.md b/README.md index d89246de953d..652da60f6ce8 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ This client supports the following Google Cloud Platform services: - [Google Cloud Compute] (#google-cloud-compute-alpha) (Alpha) - [Google Cloud Datastore] (#google-cloud-datastore) - [Google Cloud DNS] (#google-cloud-dns-alpha) (Alpha) +- [Stackdriver Logging] (#stackdriver-logging-alpha) (Alpha - Not working on App Engine Standard) - [Google Cloud Pub/Sub] (#google-cloud-pubsub-alpha) (Alpha - Not working on App Engine Standard) - [Google Cloud Resource Manager] (#google-cloud-resource-manager-alpha) (Alpha) - [Google Cloud Storage] (#google-cloud-storage) @@ -371,6 +372,75 @@ ChangeRequestInfo changeRequest = changeBuilder.build(); zone.applyChangeRequest(changeRequest); ``` +Stackdriver Logging (Alpha) +---------------------- +- [API Documentation][logging-api] +- [Official Documentation][stackdriver-logging-docs] + +*Follow the [activation instructions][stackdriver-logging-activation] to use the Stackdriver Logging +API with your project.* + +#### Preview + +Here are two code snippets showing simple usage examples from within Compute Engine/App Engine +Flexible. Note that you must [supply credentials](#authentication) and a project ID if running this +snippet elsewhere. + +The first snippet shows how to write and list log entries. Complete source code can be found on +[WriteAndListLogEntries.java](./gcloud-java-examples/src/main/java/com/google/cloud/examples/logging/snippets/WriteAndListLogEntries.java). + +```java +import com.google.cloud.MonitoredResource; +import com.google.cloud.Page; +import com.google.cloud.logging.LogEntry; +import com.google.cloud.logging.Logging; +import com.google.cloud.logging.Logging.EntryListOption; +import com.google.cloud.logging.LoggingOptions; +import com.google.cloud.logging.Payload.StringPayload; + +import java.util.Collections; +import java.util.Iterator; + +LoggingOptions options = LoggingOptions.defaultInstance(); +try(Logging logging = options.service()) { + + LogEntry firstEntry = LogEntry.builder(StringPayload.of("message")) + .logName("test-log") + .resource(MonitoredResource.builder("global") + .addLabel("project_id", options.projectId()) + .build()) + .build(); + logging.write(Collections.singleton(firstEntry)); + + Page entries = logging.listLogEntries( + EntryListOption.filter("logName=projects/" + options.projectId() + "/logs/test-log")); + Iterator entryIterator = entries.iterateAll(); + while (entryIterator.hasNext()) { + System.out.println(entryIterator.next()); + } +} +``` + +The second snippet shows how to use a `java.util.logging.Logger` to write log entries to Stackdriver +Logging. The snippet installs a Stackdriver Logging handler using +`LoggingHandler.addHandler(Logger, LoggingHandler)`. Notice that this could also be done through the +`logging.properties` file, adding the following line: +``` +com.google.cloud.examples.logging.snippets.AddLoggingHandler.handlers=com.google.cloud.logging.LoggingHandler +``` +The complete code can be found on +[AddLoggingHandler.java](./gcloud-java-examples/src/main/java/com/google/cloud/examples/logging/snippets/AddLoggingHandler.java). + +```java +import com.google.cloud.logging.LoggingHandler; + +import java.util.logging.Logger; + +Logger logger = Logger.getLogger(AddLoggingHandler.class.getName()); +LoggingHandler.addHandler(logger, new LoggingHandler()); +logger.warning("test warning"); +``` + Google Cloud Pub/Sub (Alpha) ---------------------- diff --git a/TESTING.md b/TESTING.md index 3db27bd8554f..a3d0ad770bc9 100644 --- a/TESTING.md +++ b/TESTING.md @@ -6,6 +6,7 @@ This library provides tools to help write tests for code that uses the following - [Compute] (#testing-code-that-uses-compute) - [Datastore] (#testing-code-that-uses-datastore) - [DNS] (#testing-code-that-uses-dns) +- [Logging] (#testing-code-that-uses-logging) - [PubSub] (#testing-code-that-uses-pubsub) - [Resource Manager] (#testing-code-that-uses-resource-manager) - [Storage] (#testing-code-that-uses-storage) @@ -146,6 +147,31 @@ You can test against an in-memory local DNS by following these steps: This method will block until the server thread has been terminated. +### Testing code that uses Logging + +Currently, there isn't an emulator for Stackdriver Logging, so an alternative is to create a test +project. `RemoteLoggingHelper` contains convenience methods to make setting up the test project +easier. To use this class, follow the steps below: + +1. Create a test Google Cloud project. + +2. Download a [JSON service account credentials file][create-service-account] from the Google +Developer's Console. + +3. Create a `RemoteLoggingHelper` object using your project ID and JSON key. Here is an example that +uses the `RemoteLoggingHelper` to create a metric. + ```java + RemoteLoggingHelper loggingHelper = + RemoteLoggingHelper.create(PROJECT_ID, new FileInputStream("/path/to/my/JSON/key.json")); + Logging logging = loggingHelper.options().service(); + // Pick a name for the resource with low probability of clashing + String metricName = RemoteLoggingHelper.formatForTest("test-metric"); + MetricInfo metricInfo = MetricInfo.of(name, "logName:syslog"); + Metric metric = logging.create(metricInfo); + ``` + +4. Run your tests. + ### Testing code that uses Pub/Sub #### On your machine @@ -218,31 +244,6 @@ You can test against an in-memory local Resource Manager by following these step This method will block until the server thread has been terminated. -### Testing code that uses Logging - -Currently, there isn't an emulator for Stackdriver Logging, so an alternative is to create a test -project. `RemoteLoggingHelper` contains convenience methods to make setting up the test project -easier. To use this class, follow the steps below: - -1. Create a test Google Cloud project. - -2. Download a [JSON service account credentials file][create-service-account] from the Google -Developer's Console. - -3. Create a `RemoteLoggingHelper` object using your project ID and JSON key. Here is an example that -uses the `RemoteLoggingHelper` to create a metric. - ```java - RemoteLoggingHelper loggingHelper = - RemoteLoggingHelper.create(PROJECT_ID, new FileInputStream("/path/to/my/JSON/key.json")); - Logging logging = loggingHelper.options().service(); - // Pick a name for the resource with low probability of clashing - String metricName = RemoteLoggingHelper.formatForTest("test-metric"); - MetricInfo metricInfo = MetricInfo.of(name, "logName:syslog"); - Metric metric = logging.create(metricInfo); - ``` - -4. Run your tests. - ### Testing code that uses Storage Currently, there isn't an emulator for Google Cloud Storage, so an alternative is to create a test project. `RemoteStorageHelper` contains convenience methods to make setting up and cleaning up the test project easier. To use this class, follow the steps below: diff --git a/pom.xml b/pom.xml index 289ab459bfda..1eb3a0d3612b 100644 --- a/pom.xml +++ b/pom.xml @@ -401,7 +401,7 @@ Test helpers packages - com.google.cloud.bigquery.testing:com.google.cloud.compute.testing:com.google.cloud.datastore.testing:com.google.cloud.dns.testing:com.google.cloud.pubsub.testing:com.google.cloud.resourcemanager.testing:com.google.cloud.storage.testing + com.google.cloud.bigquery.testing:com.google.cloud.compute.testing:com.google.cloud.datastore.testing:com.google.cloud.dns.testing:com.google.cloud.logging.testing:com.google.cloud.pubsub.testing:com.google.cloud.resourcemanager.testing:com.google.cloud.storage.testing Example packages @@ -409,7 +409,7 @@ SPI packages - com.google.cloud.spi:com.google.cloud.bigquery.spi:com.google.cloud.compute.spi:com.google.cloud.datastore.spi:com.google.cloud.dns.spi:com.google.cloud.pubsub.spi:com.google.cloud.pubsub.spi.*:com.google.cloud.resourcemanager.spi:com.google.cloud.storage.spi + com.google.cloud.spi:com.google.cloud.bigquery.spi:com.google.cloud.compute.spi:com.google.cloud.datastore.spi:com.google.cloud.dns.spi:com.google.cloud.logging.spi:com.google.cloud.logging.spi.*:com.google.cloud.pubsub.spi:com.google.cloud.pubsub.spi.*:com.google.cloud.resourcemanager.spi:com.google.cloud.storage.spi