Add logging to README.md and TESTING.md, fix package grouping

googleapis · Jul 20, 2016 · f923245 · f923245
1 parent 49be9ac
commit f923245
Show file tree

Hide file tree

Showing 3 changed files with 98 additions and 27 deletions.
diff --git 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<LogEntry> entries = logging.listLogEntries(
+      EntryListOption.filter("logName=projects/" + options.projectId() + "/logs/test-log"));
+  Iterator<LogEntry> 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
@@ -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
@@ -401,15 +401,15 @@
                   </group>
                   <group>
                     <title>Test helpers packages</title>
-                    <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</packages>
+                    <packages>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</packages>
                   </group>
                   <group>
                     <title>Example packages</title>
                     <packages>com.google.cloud.examples.*:com.google.cloud.nio.examples</packages>
                   </group>
                   <group>
                     <title>SPI packages</title>
-                    <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</packages>
+                    <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.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</packages>
                   </group>
                 </groups>
               </configuration>