Add few usage examples for the trace API.

6 files changed, 240 insertions, 0 deletions

diff --git a/examples/src/main/java/com/google/instrumentation/trace/BasicContextTracing.java b/examples/src/main/java/com/google/instrumentation/trace/BasicContextTracing.java
new file mode 100644
index 00000000..ef776473
--- /dev/null
+++ b/examples/src/main/java/com/google/instrumentation/trace/BasicContextTracing.java
@@ -0,0 +1,38 @@
+/*
+ * Copyright 2017, Google Inc.
+ * 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.google.instrumentation.trace;
+
+import com.google.instrumentation.common.NonThrowingCloseable;
+
+/**
+ * Example showing how to create a {@link Span}, install it to the current context and add
+ * annotations.
+ */
+public final class BasicContextTracing {
+  // Per class Tracer.
+  private static final Tracer tracer = Tracer.getTracer();
+
+  private static void doWork() {
+    // Add an annotation to the current Span.
+    tracer.getCurrentSpan().addAnnotation("This is a doWork() annotation.");
+  }
+
+  public static void main(String[] args) {
+    Span span = tracer.startSpan(null, "MyRootSpan", StartSpanOptions.getDefault());
+    try (NonThrowingCloseable ws = tracer.withSpan(span)) {
+      doWork();
+    }
+    span.end();
+  }
+}
diff --git a/examples/src/main/java/com/google/instrumentation/trace/BasicScopedTracing.java b/examples/src/main/java/com/google/instrumentation/trace/BasicScopedTracing.java
new file mode 100644
index 00000000..1c1c8c05
--- /dev/null
+++ b/examples/src/main/java/com/google/instrumentation/trace/BasicScopedTracing.java
@@ -0,0 +1,36 @@
+/*
+ * Copyright 2017, Google Inc.
+ * 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.google.instrumentation.trace;
+
+import com.google.instrumentation.common.NonThrowingCloseable;
+
+/**
+ * Example showing how to create a {@link Span} using {@link ScopedSpan}, install it in the current
+ * context, and add annotations.
+ */
+public final class BasicScopedTracing {
+  // Per class Tracer.
+  private static final Tracer tracer = Tracer.getTracer();
+
+  private static void doWork() {
+    // Add an annotation to the current Span.
+    tracer.getCurrentSpan().addAnnotation("This is a doWork() annotation.");
+  }
+
+  public static void main(String[] args) {
+    try (NonThrowingCloseable ss = tracer.startScopedSpan(null, "MyRootSpan")) {
+      doWork();
+    }
+  }
+}
diff --git a/examples/src/main/java/com/google/instrumentation/trace/BasicTracing.java b/examples/src/main/java/com/google/instrumentation/trace/BasicTracing.java
new file mode 100644
index 00000000..1bb60e44
--- /dev/null
+++ b/examples/src/main/java/com/google/instrumentation/trace/BasicTracing.java
@@ -0,0 +1,30 @@
+/*
+ * Copyright 2017, Google Inc.
+ * 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.google.instrumentation.trace;
+
+/** Example showing how to create a {@link Span} and add annotations. */
+public final class BasicTracing {
+  // Per class Tracer.
+  private static final Tracer tracer = Tracer.getTracer();
+
+  private static void doWork() {
+    try (Span span = tracer.startSpan(null, "MyRootSpan", StartSpanOptions.getDefault())) {
+      span.addAnnotation("This annotation is added directly to the span.");
+    }
+  }
+
+  public static void main(String[] args) {
+    doWork();
+  }
+}
diff --git a/examples/src/main/java/com/google/instrumentation/trace/MultiSpansContextTracing.java b/examples/src/main/java/com/google/instrumentation/trace/MultiSpansContextTracing.java
new file mode 100644
index 00000000..db1312da
--- /dev/null
+++ b/examples/src/main/java/com/google/instrumentation/trace/MultiSpansContextTracing.java
@@ -0,0 +1,53 @@
+/*
+ * Copyright 2017, Google Inc.
+ * 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.google.instrumentation.trace;
+
+import com.google.instrumentation.common.NonThrowingCloseable;
+
+/**
+ * Example showing how to create a child {@link Span}, install it to the current context and add
+ * annotations.
+ */
+public final class MultiSpansContextTracing {
+  // Per class Tracer.
+  private static final Tracer tracer = Tracer.getTracer();
+
+  private static void doSomeOtherWork() {
+    tracer.getCurrentSpan().addAnnotation("Annotation to the child Span");
+  }
+
+  private static void doSomeMoreWork() {
+    // Create a child Span of the current Span.
+    Span span =
+        tracer.startSpan(tracer.getCurrentSpan(), "MyChildSpan", StartSpanOptions.getDefault());
+    try (NonThrowingCloseable ws = tracer.withSpan(span)) {
+      doSomeOtherWork();
+    }
+    span.end();
+  }
+
+  private static void doWork() {
+    tracer.getCurrentSpan().addAnnotation("Annotation to the root Span before child is created.");
+    doSomeMoreWork();
+    tracer.getCurrentSpan().addAnnotation("Annotation to the root Span after child is ended.");
+  }
+
+  public static void main(String[] args) {
+    Span span = tracer.startSpan(null, "MyRootSpan", StartSpanOptions.getDefault());
+    try (NonThrowingCloseable ws = tracer.withSpan(span)) {
+      doWork();
+    }
+    span.end();
+  }
+}
diff --git a/examples/src/main/java/com/google/instrumentation/trace/MultiSpansScopedTracing.java b/examples/src/main/java/com/google/instrumentation/trace/MultiSpansScopedTracing.java
new file mode 100644
index 00000000..ceadb289
--- /dev/null
+++ b/examples/src/main/java/com/google/instrumentation/trace/MultiSpansScopedTracing.java
@@ -0,0 +1,48 @@
+/*
+ * Copyright 2017, Google Inc.
+ * 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.google.instrumentation.trace;
+
+import com.google.instrumentation.common.NonThrowingCloseable;
+
+/**
+ * Example showing how to create a child {@link Span} using {@link ScopedSpan}, install it in the
+ * current context, and add annotations.
+ */
+public final class MultiSpansScopedTracing {
+  // Per class Tracer.
+  private static final Tracer tracer = Tracer.getTracer();
+
+  private static void doSomeOtherWork() {
+    tracer.getCurrentSpan().addAnnotation("Annotation to the child Span");
+  }
+
+  private static void doSomeMoreWork() {
+    // Create a child Span of the current Span.
+    try (NonThrowingCloseable ss = tracer.startScopedSpan("MyChildSpan")) {
+      doSomeOtherWork();
+    }
+  }
+
+  private static void doWork() {
+    tracer.getCurrentSpan().addAnnotation("Annotation to the root Span before child is created.");
+    doSomeMoreWork();
+    tracer.getCurrentSpan().addAnnotation("Annotation to the root Span after child is ended.");
+  }
+
+  public static void main(String[] args) {
+    try (NonThrowingCloseable ss = tracer.startScopedSpan(null, "MyRootSpan")) {
+      doWork();
+    }
+  }
+}
diff --git a/examples/src/main/java/com/google/instrumentation/trace/MultiSpansTracing.java b/examples/src/main/java/com/google/instrumentation/trace/MultiSpansTracing.java
new file mode 100644
index 00000000..2351198f
--- /dev/null
+++ b/examples/src/main/java/com/google/instrumentation/trace/MultiSpansTracing.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright 2017, Google Inc.
+ * 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.google.instrumentation.trace;
+
+/** Example showing how to directly create a child {@link Span} and add annotations. */
+public final class MultiSpansTracing {
+  // Per class Tracer.
+  private static final Tracer tracer = Tracer.getTracer();
+
+  private static void doWork() {
+    try (Span rootSpan = tracer.startSpan(null, "MyRootSpan", StartSpanOptions.getDefault())) {
+      rootSpan.addAnnotation("Annotation to the root Span before child is created.");
+      try (Span childSpan =
+          tracer.startSpan(rootSpan, "MyChildSpan", StartSpanOptions.getDefault())) {
+        childSpan.addAnnotation("Annotation to the child Span");
+      }
+      rootSpan.addAnnotation("Annotation to the root Span after child is ended.");
+    }
+  }
+
+  public static void main(String[] args) {
+    doWork();
+  }
+}