Merge pull request #271 from bogdandrutu/traceexport

Add a TraceExporter class that allows exporting Span data to different trace services.

11 files changed, 168 insertions, 4 deletions

diff --git a/core_impl/src/main/java/com/google/instrumentation/trace/SpanData.java b/core/src/main/java/com/google/instrumentation/trace/SpanData.java
index ce1a7a84..579b0373 100644
--- a/core_impl/src/main/java/com/google/instrumentation/trace/SpanData.java
+++ b/core/src/main/java/com/google/instrumentation/trace/SpanData.java
@@ -147,7 +147,11 @@ public abstract class SpanData {
 
   SpanData() {}
 
-  /** A timed event representation. It can be a timed {@link Annotation} or {@link NetworkEvent}. */
+  /**
+   * A timed event representation.
+   *
+   * @param <T> the type of value that is timed.
+   */
   @Immutable
   @AutoValue
   public abstract static class TimedEvent<T> {
@@ -180,6 +184,11 @@ public abstract class SpanData {
     TimedEvent() {}
   }
 
+  /**
+   * A list of timed events and the number of dropped events representation.
+   *
+   * @param <T> the type of value that is timed.
+   */
   @Immutable
   @AutoValue
   public abstract static class TimedEvents<T> {
@@ -215,6 +224,9 @@ public abstract class SpanData {
     TimedEvents() {}
   }
 
+  /**
+   * A set of attributes and the number of dropped attributes representation.
+   */
   @Immutable
   @AutoValue
   public abstract static class Attributes {
@@ -252,6 +264,9 @@ public abstract class SpanData {
     Attributes() {}
   }
 
+  /**
+   * A list of links and the number of dropped links representation.
+   */
   @Immutable
   @AutoValue
   public abstract static class Links {
diff --git a/core/src/main/java/com/google/instrumentation/trace/TraceComponent.java b/core/src/main/java/com/google/instrumentation/trace/TraceComponent.java
index b00b6cf6..2d7de903 100644
--- a/core/src/main/java/com/google/instrumentation/trace/TraceComponent.java
+++ b/core/src/main/java/com/google/instrumentation/trace/TraceComponent.java
@@ -48,6 +48,14 @@ public abstract class TraceComponent {
    */
   public abstract Clock getClock();
 
+  /**
+   * Returns the {@link TraceExporter} with the provided implementation. If no implementation is
+   * provided then no-op implementations will be used.
+   *
+   * @return the {@link TraceExporter} implementation.
+   */
+  public abstract TraceExporter getTraceExporter();
+
   // Disallow external overrides until we define the final API.
   TraceComponent() {}
 
@@ -76,6 +84,11 @@ public abstract class TraceComponent {
       return ZeroTimeClock.getInstance();
     }
 
+    @Override
+    public TraceExporter getTraceExporter() {
+      return TraceExporter.getNoopTraceExporter();
+    }
+
     private NoopTraceComponent() {}
   }
 }
diff --git a/core/src/main/java/com/google/instrumentation/trace/TraceExporter.java b/core/src/main/java/com/google/instrumentation/trace/TraceExporter.java
new file mode 100644
index 00000000..d9aa074f
--- /dev/null
+++ b/core/src/main/java/com/google/instrumentation/trace/TraceExporter.java
@@ -0,0 +1,92 @@
+/*
+ * 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 javax.annotation.Nullable;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * The main exporting API for the trace library.
+ *
+ * <p>Implementation MUST ensure that all functions are thread safe.
+ */
+@ThreadSafe
+public abstract class TraceExporter {
+  private static final NoopTraceExporter noopTraceExporter = new NoopTraceExporter();
+
+  /**
+   * Registers a new service handler that is used by the library to export trace data.
+   *
+   * <p>Example of usage:
+   *
+   * <pre>{@code
+   * public static void main(String[] args) {
+   *   Tracing.getTraceExporter().registerServiceHandler(
+   *       "com.google.stackdriver", new StackdriverServiceHandler());
+   *   // ...
+   * }
+   * }</pre>
+   *
+   * @param name the name of the service handler. Must be unique for each service.
+   * @param serviceHandler the service handler that is called for each ended sampled span.
+   */
+  public abstract void registerServiceHandler(String name, ServiceHandler serviceHandler);
+
+  /**
+   * Unregisters the service handler with the provided name.
+   *
+   * @param name the name of the service handler that will be unregistered.
+   */
+  public abstract void unregisterServiceHandler(String name);
+
+  /**
+   * An abstract class that allows different tracing services to export recorded data for sampled
+   * spans in their own format.
+   *
+   * <p>To export data this MUST be register to to the TraceExporter using {@link
+   * #registerServiceHandler(String, ServiceHandler)}.
+   */
+  public abstract static class ServiceHandler {
+
+    /**
+     * It is called every time after a sampled (see {@link TraceOptions#isSampled()}) {@link Span}
+     * is ended.
+     *
+     * <p>This may be called from a different thread than the one that called {@link Span#end()}.
+     *
+     * <p>Implementation SHOULD not block the calling thread. It should execute the export on a
+     * different thread if possible.
+     *
+     * @param spanData the immutable representation of all data collected by the {@code Span}.
+     */
+    public abstract void export(SpanData spanData);
+  }
+
+  /**
+   * Returns the no-op implementation of the {@code TraceExporter}.
+   *
+   * @return the no-op implementation of the {@code TraceExporter}.
+   */
+  static TraceExporter getNoopTraceExporter() {
+    return noopTraceExporter;
+  }
+
+  private static final class NoopTraceExporter extends TraceExporter {
+    @Override
+    public void registerServiceHandler(String name, @Nullable ServiceHandler serviceHandler) {}
+
+    @Override
+    public void unregisterServiceHandler(String name) {}
+  }
+}
diff --git a/core/src/main/java/com/google/instrumentation/trace/Tracing.java b/core/src/main/java/com/google/instrumentation/trace/Tracing.java
index f5b0d7fc..aa11824f 100644
--- a/core/src/main/java/com/google/instrumentation/trace/Tracing.java
+++ b/core/src/main/java/com/google/instrumentation/trace/Tracing.java
@@ -52,6 +52,15 @@ public final class Tracing {
     return traceComponent.getClock();
   }
 
+  /**
+   * Returns the global {@link TraceExporter}.
+   *
+   * @return the global {@code TraceExporter}.
+   */
+  public static TraceExporter getTraceExporter() {
+    return traceComponent.getTraceExporter();
+  }
+
   // Any provider that may be used for TraceComponent can be added here.
   @VisibleForTesting
   static TraceComponent loadTraceComponent(ClassLoader classLoader) {
diff --git a/core_impl/src/test/java/com/google/instrumentation/trace/SpanDataTest.java b/core/src/test/java/com/google/instrumentation/trace/SpanDataTest.java
index 9b2e6d7a..9b2e6d7a 100644
--- a/core_impl/src/test/java/com/google/instrumentation/trace/SpanDataTest.java
+++ b/core/src/test/java/com/google/instrumentation/trace/SpanDataTest.java
diff --git a/core/src/test/java/com/google/instrumentation/trace/TraceComponentTest.java b/core/src/test/java/com/google/instrumentation/trace/TraceComponentTest.java
index d7510d4b..9cae9211 100644
--- a/core/src/test/java/com/google/instrumentation/trace/TraceComponentTest.java
+++ b/core/src/test/java/com/google/instrumentation/trace/TraceComponentTest.java
@@ -38,4 +38,10 @@ public class TraceComponentTest {
   public void defaultClock() {
     assertThat(TraceComponent.getNoopTraceComponent().getClock()).isInstanceOf(ZeroTimeClock.class);
   }
+
+  @Test
+  public void defaultTraceExporter() {
+    assertThat(TraceComponent.getNoopTraceComponent().getTraceExporter())
+        .isSameAs(TraceExporter.getNoopTraceExporter());
+  }
 }
diff --git a/core/src/test/java/com/google/instrumentation/trace/TracingTest.java b/core/src/test/java/com/google/instrumentation/trace/TracingTest.java
index 83f881d4..24006ecf 100644
--- a/core/src/test/java/com/google/instrumentation/trace/TracingTest.java
+++ b/core/src/test/java/com/google/instrumentation/trace/TracingTest.java
@@ -65,4 +65,9 @@ public class TracingTest {
     assertThat(Tracing.getBinaryPropagationHandler())
         .isSameAs(BinaryPropagationHandler.getNoopBinaryPropagationHandler());
   }
+
+  @Test
+  public void defaultTraceExporter() {
+    assertThat(Tracing.getTraceExporter()).isSameAs(TraceExporter.getNoopTraceExporter());
+  }
 }
diff --git a/core_impl/src/main/java/com/google/instrumentation/trace/TraceComponentImplBase.java b/core_impl/src/main/java/com/google/instrumentation/trace/TraceComponentImplBase.java
index 6f72d417..ae326652 100644
--- a/core_impl/src/main/java/com/google/instrumentation/trace/TraceComponentImplBase.java
+++ b/core_impl/src/main/java/com/google/instrumentation/trace/TraceComponentImplBase.java
@@ -21,6 +21,7 @@ public class TraceComponentImplBase extends TraceComponent {
   private static final BinaryPropagationHandler binaryPropagationHandler =
       BinaryPropagationHandlerImpl.INSTANCE;
   private final Clock clock;
+  private final TraceExporter traceExporter = TraceExporter.getNoopTraceExporter();
 
   TraceComponentImplBase(Clock clock) {
     this.clock = clock;
@@ -40,4 +41,9 @@ public class TraceComponentImplBase extends TraceComponent {
   public final Clock getClock() {
     return clock;
   }
+
+  @Override
+  public TraceExporter getTraceExporter() {
+    return traceExporter;
+  }
 }
diff --git a/core_impl_android/src/test/java/com/google/instrumentation/trace/TraceComponentImplTest.java b/core_impl_android/src/test/java/com/google/instrumentation/trace/TraceComponentImplTest.java
index 814d10a0..26f7c8b1 100644
--- a/core_impl_android/src/test/java/com/google/instrumentation/trace/TraceComponentImplTest.java
+++ b/core_impl_android/src/test/java/com/google/instrumentation/trace/TraceComponentImplTest.java
@@ -32,11 +32,17 @@ public class TraceComponentImplTest {
   @Test
   public void implementationOfBinaryPropagationHandler() {
     assertThat(Tracing.getBinaryPropagationHandler())
-        .isSameAs(BinaryPropagationHandlerImpl.INSTANCE);
+        .isInstanceOf(BinaryPropagationHandlerImpl.class);
   }
 
   @Test
   public void implementationOfClock() {
     assertThat(Tracing.getClock()).isInstanceOf(MillisClock.class);
   }
+
+  @Test
+  public void implementationOfTraceExporter() {
+    // TODO(bdrutu): Change this when TraceExporterImpl is available.
+    assertThat(Tracing.getTraceExporter()).isSameAs(TraceExporter.getNoopTraceExporter());
+  }
 }
diff --git a/core_impl_java_7/src/test/java/com/google/instrumentation/trace/TraceComponentImplTest.java b/core_impl_java_7/src/test/java/com/google/instrumentation/trace/TraceComponentImplTest.java
index 814d10a0..26f7c8b1 100644
--- a/core_impl_java_7/src/test/java/com/google/instrumentation/trace/TraceComponentImplTest.java
+++ b/core_impl_java_7/src/test/java/com/google/instrumentation/trace/TraceComponentImplTest.java
@@ -32,11 +32,17 @@ public class TraceComponentImplTest {
   @Test
   public void implementationOfBinaryPropagationHandler() {
     assertThat(Tracing.getBinaryPropagationHandler())
-        .isSameAs(BinaryPropagationHandlerImpl.INSTANCE);
+        .isInstanceOf(BinaryPropagationHandlerImpl.class);
   }
 
   @Test
   public void implementationOfClock() {
     assertThat(Tracing.getClock()).isInstanceOf(MillisClock.class);
   }
+
+  @Test
+  public void implementationOfTraceExporter() {
+    // TODO(bdrutu): Change this when TraceExporterImpl is available.
+    assertThat(Tracing.getTraceExporter()).isSameAs(TraceExporter.getNoopTraceExporter());
+  }
 }
diff --git a/core_impl_java_8/src/test/java/com/google/instrumentation/trace/TraceComponentImplTest.java b/core_impl_java_8/src/test/java/com/google/instrumentation/trace/TraceComponentImplTest.java
index 0e426e1a..7a20e31a 100644
--- a/core_impl_java_8/src/test/java/com/google/instrumentation/trace/TraceComponentImplTest.java
+++ b/core_impl_java_8/src/test/java/com/google/instrumentation/trace/TraceComponentImplTest.java
@@ -32,11 +32,17 @@ public class TraceComponentImplTest {
   @Test
   public void implementationOfBinaryPropagationHandler() {
     assertThat(Tracing.getBinaryPropagationHandler())
-        .isSameAs(BinaryPropagationHandlerImpl.INSTANCE);
+        .isInstanceOf(BinaryPropagationHandlerImpl.class);
   }
 
   @Test
   public void implementationOfClock() {
     assertThat(Tracing.getClock()).isInstanceOf(InstantClock.class);
   }
+
+  @Test
+  public void implementationOfTraceExporter() {
+    // TODO(bdrutu): Change this when TraceExporterImpl is available.
+    assertThat(Tracing.getTraceExporter()).isSameAs(TraceExporter.getNoopTraceExporter());
+  }
 }