feat: Add a sample snippet for use of the tailLogEntries API

Add sample in Java for use of tailLogEntries API * 🦉 Updates from OwlBot See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
googleapis · Sep 17, 2021 · 8115888 · 8115888
1 parent 5a7845a
commit 8115888
Show file tree

Hide file tree

Showing 9 changed files with 132 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -42,7 +42,7 @@ If you are using Maven without BOM, add this to your dependencies:
 <dependency>
   <groupId>com.google.cloud</groupId>
   <artifactId>google-cloud-logging</artifactId>
-  <version>3.1.1</version>
+  <version>3.1.2</version>
 </dependency>
 
 ```
@@ -235,6 +235,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/java-logging/tree/
 | List Logs | [source code](https://github.com/googleapis/java-logging/blob/master/samples/snippets/src/main/java/com/example/logging/ListLogs.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-logging&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/logging/ListLogs.java) |
 | Log Entry Write Http Request | [source code](https://github.com/googleapis/java-logging/blob/master/samples/snippets/src/main/java/com/example/logging/LogEntryWriteHttpRequest.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-logging&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/logging/LogEntryWriteHttpRequest.java) |
 | Quickstart Sample | [source code](https://github.com/googleapis/java-logging/blob/master/samples/snippets/src/main/java/com/example/logging/QuickstartSample.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-logging&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/logging/QuickstartSample.java) |
+| Tail Log Entries | [source code](https://github.com/googleapis/java-logging/blob/master/samples/snippets/src/main/java/com/example/logging/TailLogEntries.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-logging&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/logging/TailLogEntries.java) |
 | Quickstart | [source code](https://github.com/googleapis/java-logging/blob/master/samples/snippets/src/main/java/com/example/logging/jul/Quickstart.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-logging&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/logging/jul/Quickstart.java) |
 | Example Enhancer | [source code](https://github.com/googleapis/java-logging/blob/master/samples/snippets/src/main/java/com/example/logging/jul/enhancers/ExampleEnhancer.java) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/java-logging&page=editor&open_in_editor=samples/snippets/src/main/java/com/example/logging/jul/enhancers/ExampleEnhancer.java) |
 

diff --git a/google-cloud-logging/src/main/java/com/google/cloud/logging/JavaTimeConversions.java b/google-cloud-logging/src/main/java/com/google/cloud/logging/JavaTimeConversions.java
@@ -16,6 +16,7 @@
 
 package com.google.cloud.logging;
 
+import static com.google.common.base.Preconditions.checkNotNull;
 import static com.google.common.math.LongMath.checkedAdd;
 import static com.google.common.math.LongMath.checkedSubtract;
 
@@ -33,8 +34,8 @@
  * The class complements convertion methods that are currently not supported in the published
  * protobuf-java-util. After migrating protobuf-java-util to Java 8 this class can be removed.
  *
- * @see <a
- *     href="https://mvnrepository.com/artifact/com.google.protobuf/protobuf-java-util">protobuf-java-util</a>
+ * @see <a href=
+ *     "https://mvnrepository.com/artifact/com.google.protobuf/protobuf-java-util">protobuf-java-util</a>
  */
 class JavaTimeConversions {
   static final long NANOS_PER_SECOND = 1000000000;
@@ -48,6 +49,7 @@ private JavaTimeConversions() {}
    *     Timestamps#isValid}.
    */
   public static Instant toJavaInstant(Timestamp timestamp) {
+    checkNotNull(timestamp);
     timestamp = normalizedTimestamp(timestamp.getSeconds(), timestamp.getNanos());
     return Instant.ofEpochSecond(timestamp.getSeconds(), timestamp.getNanos());
   }
@@ -59,6 +61,7 @@ public static Instant toJavaInstant(Timestamp timestamp) {
    *     a {@link Timestamp}. See {@link Timestamps#isValid}.
    */
   public static Timestamp toProtoTimestamp(Instant instant) {
+    checkNotNull(instant);
     return normalizedTimestamp(instant.getEpochSecond(), instant.getNano());
   }
 

diff --git a/google-cloud-logging/src/main/java/com/google/cloud/logging/LogEntryIterator.java b/google-cloud-logging/src/main/java/com/google/cloud/logging/LogEntryIterator.java
@@ -21,7 +21,14 @@
 import java.util.Iterator;
 import java.util.LinkedList;
 
+/**
+ * The class implements {@see Iterator} interface over {@see LogEntry} by iterating through {@see
+ * TailLogEntriesResponse} streamed by {@code BidiStream}. This class is instantiated by {@see
+ * LogEntryServerStream} and is not intended to be used explicitly.
+ */
 public class LogEntryIterator implements Iterator<LogEntry> {
+  // TODO: consider converting this to use generics instead of
+  // fixed TailLogEntriesResponse
   private final Iterator<TailLogEntriesResponse> streamIterator;
   private final LinkedList<LogEntry> buffer = new LinkedList<>();
 

diff --git a/google-cloud-logging/src/main/java/com/google/cloud/logging/LogEntryServerStream.java b/google-cloud-logging/src/main/java/com/google/cloud/logging/LogEntryServerStream.java
@@ -22,6 +22,26 @@
 import com.google.logging.v2.TailLogEntriesResponse;
 import java.util.Iterator;
 
+/**
+ * The class implements {@Iterable} interface over {@see LogEntry}. It wraps around {@BidiStream}
+ * bi-directional gRPC stream to support iterating through ingested responses. The class uses {@see
+ * LogEntryIterator} to iterate through the processed responses. The stream should be explicitly
+ * canceled by calling {@see LogEntryServerStream#cancel()} method. The class does not provide
+ * recovery or resuming functionality over the stream.
+ *
+ * <p>To iterate run:
+ *
+ * <pre>{@code
+ * LogEntryServerStream stream;
+ * // code to initialize stream
+ * for (LogEntry log : stream) {
+ *   // do something with logs
+ * }
+ * stream.cancel();
+ * }</pre>
+ *
+ * <p>The iteration can be blocked on waiting for another response sent in the stream.
+ */
 public class LogEntryServerStream implements Iterable<LogEntry> {
   private final BidiStream<TailLogEntriesRequest, TailLogEntriesResponse> serverStream;
 

diff --git a/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingImpl.java b/google-cloud-logging/src/main/java/com/google/cloud/logging/LoggingImpl.java
@@ -924,7 +924,7 @@ public ApiFuture<AsyncPage<LogEntry>> listLogEntriesAsync(EntryListOption... opt
     return listLogEntriesAsync(getOptions(), optionMap(options));
   }
 
-  static TailLogEntriesRequest tailLogEntriesRequest(
+  static TailLogEntriesRequest buildTailLogEntriesRequest(
       Map<Option.OptionType, ?> options, String defaultProjectId) {
     TailLogEntriesRequest.Builder builder = TailLogEntriesRequest.newBuilder();
 
@@ -967,7 +967,7 @@ public LogEntryServerStream tailLogEntries(TailOption... options) {
     BidiStream<TailLogEntriesRequest, TailLogEntriesResponse> bidiStream =
         serviceOptions.getLoggingRpcV2().getTailLogEntriesStream();
     final TailLogEntriesRequest request =
-        tailLogEntriesRequest(optionMap(options), serviceOptions.getProjectId());
+        buildTailLogEntriesRequest(optionMap(options), serviceOptions.getProjectId());
     bidiStream.send(request);
     return new LogEntryServerStream(bidiStream);
   }

diff --git a/google-cloud-logging/src/test/java/com/google/cloud/logging/TailLogEntriesTest.java b/google-cloud-logging/src/test/java/com/google/cloud/logging/TailLogEntriesTest.java
@@ -43,7 +43,7 @@ public class TailLogEntriesTest {
   @Test
   public void testTailOptions() {
     TailLogEntriesRequest request =
-        LoggingImpl.tailLogEntriesRequest(
+        LoggingImpl.buildTailLogEntriesRequest(
             LoggingImpl.optionMap(
                 TailOption.filter(FILTER),
                 TailOption.bufferWindow(WINDOW),
@@ -66,7 +66,7 @@ public void testTailOptions() {
   @Test
   public void testEmptyTailOptions() {
     TailLogEntriesRequest request =
-        LoggingImpl.tailLogEntriesRequest(LoggingImpl.optionMap(), DEFAULT_PROJECT_ID);
+        LoggingImpl.buildTailLogEntriesRequest(LoggingImpl.optionMap(), DEFAULT_PROJECT_ID);
     assertThat(request.getFilter()).isEqualTo("");
     assertThat(request.getBufferWindow()).isEqualTo(Duration.newBuilder().build());
     assertThat(request.getResourceNamesList()).containsExactly("projects/" + DEFAULT_PROJECT_ID);

diff --git a/google-cloud-logging/src/test/java/com/google/cloud/logging/it/ITTailLogsTest.java b/google-cloud-logging/src/test/java/com/google/cloud/logging/it/ITTailLogsTest.java
@@ -34,10 +34,6 @@ public class ITTailLogsTest extends BaseSystemTest {
   private static final MonitoredResource GLOBAL_RESOURCE =
       MonitoredResource.newBuilder("global").build();
 
-  // @BeforeClass
-  // public static void configureWriteLogs() {
-  // }
-
   @AfterClass
   public static void cleanUpLogs() throws InterruptedException {
     assertTrue(cleanupLog(LOG_ID));
@@ -83,7 +79,9 @@ public void testTailLogEntries() throws InterruptedException {
     assertEquals(testLogEntry.getLogName(), resultEntry.getLogName());
     assertEquals(
         testLogEntry.getHttpRequest().getStatus(), resultEntry.getHttpRequest().getStatus());
+    // assert equals for Payload objects
     assertTrue(testLogEntry.getPayload().equals(resultEntry.getPayload()));
+    // assert equals for Map<String,String> objects
     assertTrue(testLogEntry.getLabels().equals(resultEntry.getLabels()));
   }
 }
diff --git a/samples/snippets/src/main/java/com/example/logging/TailLogEntries.java b/samples/snippets/src/main/java/com/example/logging/TailLogEntries.java
@@ -0,0 +1,55 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.logging;
+
+// [START logging_write_log_entry]
+import com.google.cloud.logging.LogEntry;
+import com.google.cloud.logging.LogEntryServerStream;
+import com.google.cloud.logging.Logging;
+import com.google.cloud.logging.Logging.TailOption;
+import com.google.cloud.logging.LoggingOptions;
+
+public class TailLogEntries {
+
+  public static void main(String[] args) throws Exception {
+    // TODO(developer): Optionally provide the logname as an argument.
+    String logName = args.length > 0 ? args[0] : "";
+
+    LoggingOptions options = LoggingOptions.getDefaultInstance();
+    try (Logging logging = options.getService()) {
+
+      // Optionally compose a filter to tail log entries only from specific log
+      LogEntryServerStream stream;
+
+      if (logName != "") {
+        stream =
+            logging.tailLogEntries(
+                TailOption.filter(
+                    "logName=projects/" + options.getProjectId() + "/logs/" + logName));
+      } else {
+        stream = logging.tailLogEntries();
+      }
+      System.out.println("start streaming..");
+      for (LogEntry log : stream) {
+        System.out.println(log);
+        // cancel infinite streaming after receiving first entry
+        stream.cancel();
+      }
+    }
+  }
+}
+// [END logging_write_log_entry]
diff --git a/samples/snippets/src/test/java/com/example/logging/LoggingIT.java b/samples/snippets/src/test/java/com/example/logging/LoggingIT.java
@@ -64,19 +64,18 @@ public void setUp() {
   public void tearDown() {
     // Clean up created logs
     deleteLog(TEST_LOG);
-
     System.setOut(null);
   }
 
   @Test
-  public void testQuickstart() throws Exception {
+  public void testQuickstartSample() throws Exception {
     QuickstartSample.main(TEST_LOG);
     String got = bout.toString();
     assertThat(got).contains(String.format("Logged: %s", STRING_PAYLOAD));
   }
 
   @Test(timeout = 60000)
-  public void testListLogEntries() throws Exception {
+  public void testListLogEntriesSample() throws Exception {
     // write a log entry
     LogEntry entry =
         LogEntry.newBuilder(StringPayload.of(STRING_PAYLOAD2))
@@ -99,7 +98,7 @@ public void testListLogEntries() throws Exception {
   }
 
   @Test(timeout = 60000)
-  public void testWriteLogHttpRequest() throws Exception {
+  public void testWriteLogHttpRequestSample() throws Exception {
     HttpRequest request =
         HttpRequest.newBuilder()
             .setRequestUrl("www.example.com")
@@ -126,7 +125,7 @@ public void testWriteLogHttpRequest() throws Exception {
   }
 
   @Test(timeout = 60000)
-  public void testListLogNames_shouldPass() throws Exception {
+  public void testListLogNamesSample() throws Exception {
     ListLogs.main();
     // Check for mocked STDOUT having data
     while (bout.toString().isEmpty()) {
@@ -135,4 +134,37 @@ public void testListLogNames_shouldPass() throws Exception {
 
     assertThat(bout.toString().contains(GOOGLEAPIS_AUDIT_LOGNAME)).isTrue();
   }
+
+  @Test(timeout = 60000)
+  public void testTailLogEntriesSample() throws Exception {
+    Runnable task =
+        () -> {
+          // wait 10 seconds to allow establishing tail stream in the sample
+          try {
+            Thread.sleep(10_000);
+            try (Logging logging = LoggingOptions.getDefaultInstance().getService()) {
+              // create an instance of LogEntry with HTTP request
+              LogEntry logEntry =
+                  LogEntry.newBuilder(StringPayload.of(STRING_PAYLOAD))
+                      .setLogName(TEST_LOG)
+                      .setResource(MonitoredResource.newBuilder("global").build())
+                      .build();
+              // Writes the log entry asynchronously
+              logging.write(Collections.singleton(logEntry));
+            }
+          } catch (Exception t) {
+            System.out.println("Failed to write log entry:\n" + t)
+          }
+        };
+    Thread thread = new Thread(task);
+    thread.start();
+
+    TailLogEntries.main(new String[] {TEST_LOG});
+
+    // Check for mocked STDOUT having data
+    while (bout.toString().isEmpty()) {
+      Thread.sleep(1000);
+    }
+    assertThat(bout.toString().contains(STRING_PAYLOAD)).isTrue();
+  }
 }