Require all span and trace creation through Tracer

dd-trace-ext/src/main/java/datadog/trace/tracer/ext/Scope.java

@@ -4,13 +4,13 @@ import datadog.trace.tracer.Span;
 import datadog.trace.tracer.Trace;
 
 /**
- * A scope holds a single span or trace continuation and may optionally close out its span or
+ * A scope holds a single span or trace continuation and may optionally finish its span or
  * continuation.
  *
  * <p>To create a scope, see {@link TracerContext#pushScope(Span, boolean)} and {@link
  * TracerContext#pushScope(Trace.Continuation, boolean)}.
  *
- * <p>All created scopes must be closed with {@link }
+ * <p>All created scopes must be closed with {@link Scope#close()}
  */
 public interface Scope {
   /** Get the span held by this scope. */

dd-trace-ext/src/main/java/datadog/trace/tracer/ext/TracerContext.java

@@ -81,8 +81,8 @@ public final class TracerContext {
    */
   public void popScope(Scope scope) {}
 
-  /** @return The scope on the top of this scope stack or null if there is no active scope. */
+  /** @return The scope on the top of this scope-stack or null if there is no active scope. */
-  public Scope topOfScopeStack() {
+  public Scope peekScope() {
     return null;
   }
 }

dd-trace/src/main/java/datadog/trace/tracer/Span.java

@@ -5,7 +5,7 @@ package datadog.trace.tracer;
  *
  * <p>All spans are thread safe.
  *
- * <p>Spans may not be constructed individually, but created through a {@link Trace}
+ * <p>To create a Span, see {@link Tracer#buildTrace()}
  */
 public interface Span {
 

dd-trace/src/main/java/datadog/trace/tracer/SpanImpl.java

@@ -1,9 +1,5 @@
-package datadog.trace.tracer.impl;
+package datadog.trace.tracer;
 
-import datadog.trace.tracer.Clock;
-import datadog.trace.tracer.Span;
-import datadog.trace.tracer.SpanContext;
-import datadog.trace.tracer.Trace;
 import java.util.Map;
 
 public class SpanImpl implements Span {
@@ -33,17 +29,19 @@ public class SpanImpl implements Span {
   /**
    * Create a span with a start time of the current timestamp.
    *
+   * @param parentContext identifies the parent of this span. May be null.
    * @param clock The clock to use to measure the span's duration.
    */
-  SpanImpl(final Clock clock) {}
+  SpanImpl(final SpanContext parentContext, final Clock clock) {}
 
   /**
    * Create a span with the a specific start timestamp.
    *
+   * @param parentContext identifies the parent of this span. May be null.
    * @param clock The clock to use to measure the span's duration.
-   * @param startTimeNanoseconds Epoch time in nanoseconds when this span started.
+   * @param startTimestampNanoseconds Epoch time in nanoseconds when this span started.
    */
-  SpanImpl(final Clock clock, final long startTimeNanoseconds) {}
+  SpanImpl(final SpanContext parentContext, final Clock clock, final long startTimestampNanoseconds) {}
 
   @Override
   public Trace getTrace() {

dd-trace/src/main/java/datadog/trace/tracer/Trace.java

@@ -6,6 +6,8 @@ package datadog.trace.tracer;
  *
  * <p>A trace will be written when all of its spans are finished and all trace continuations are
  * closed.
+ *
+ * <p>To create a Trace, see {@link Tracer#buildTrace()}
  */
 public interface Trace {
   /** Get the tracer which created this trace. */

dd-trace/src/main/java/datadog/trace/tracer/TraceImpl.java

@@ -1,6 +1,5 @@
-package datadog.trace.tracer.impl;
+package datadog.trace.tracer;
 
-import datadog.trace.tracer.Span;
 import datadog.trace.tracer.writer.Writer;
 import java.util.List;
 import java.util.concurrent.atomic.AtomicInteger;
@@ -27,4 +26,11 @@ public class TraceImpl {
    * relying on getRootSpan() will break.
    */
   private final List<Span> spans = null;
+
+  /**
+   * Create a new Trace.
+   *
+   * @param tracer the Tracer to apply settings from.
+   */
+  TraceImpl(Tracer tracer) {}
 }

dd-trace/src/main/java/datadog/trace/tracer/Tracer.java

@@ -7,13 +7,34 @@ import datadog.trace.tracer.writer.Writer;
 /** A Tracer creates {@link Trace}s and holds common settings across traces. */
 public class Tracer {
   /** Default service name if none provided on the trace or span */
-  final String serviceName = null;
+  private final String serviceName = null;
   /** Writer is an charge of reporting traces and spans to the desired endpoint */
-  final Writer writer = null;
+  private final Writer writer = null;
   /** Sampler defines the sampling policy in order to reduce the number of traces for instance */
-  final Sampler sampler = null;
+  private final Sampler sampler = null;
   /** Settings for this tracer. */
-  final Config config = null;
+  private final Config config = null;
+  /** The clock to use for tracing. */
+  private final Clock clock = null;
+
+  /**
+   * Construct a new trace using this tracer's settings and return the root span.
+   *
+   * @return The root span of the new trace.
+   */
+  public Span buildTrace() {
+    return null;
+  }
+
+  /**
+   * Construct a new trace using this tracer's settings and return the root span.
+   *
+   * @param rootSpanStartTimestampNanoseconds Epoch time in nanoseconds when the root span started.
+   * @return The root span of the new trace.
+   */
+  public Span buildTrace(final long rootSpanStartTimestampNanoseconds) {
+    return null;
+  }
 
   // TODO: doc inject and extract