To create a scope, see {@link TracerContext#pushScope(Span, boolean)} and {@link * TracerContext#pushScope(Trace.Continuation, boolean)}. * - *
All created scopes must be closed with {@link } + *
All created scopes must be closed with {@link Scope#close()} */ public interface Scope { /** Get the span held by this scope. */ diff --git a/dd-trace-ext/src/main/java/datadog/trace/tracer/ext/TracerContext.java b/dd-trace-ext/src/main/java/datadog/trace/tracer/ext/TracerContext.java index ce31b8bed7..4179433d1d 100644 --- a/dd-trace-ext/src/main/java/datadog/trace/tracer/ext/TracerContext.java +++ b/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. */ - public Scope topOfScopeStack() { + /** @return The scope on the top of this scope-stack or null if there is no active scope. */ + public Scope peekScope() { return null; } } diff --git a/dd-trace/src/main/java/datadog/trace/tracer/Span.java b/dd-trace/src/main/java/datadog/trace/tracer/Span.java index 56db15c864..0d2bd73056 100644 --- a/dd-trace/src/main/java/datadog/trace/tracer/Span.java +++ b/dd-trace/src/main/java/datadog/trace/tracer/Span.java @@ -5,7 +5,7 @@ package datadog.trace.tracer; * *
All spans are thread safe. * - *
Spans may not be constructed individually, but created through a {@link Trace} + *
To create a Span, see {@link Tracer#buildTrace()} */ public interface Span { diff --git a/dd-trace/src/main/java/datadog/trace/tracer/impl/SpanImpl.java b/dd-trace/src/main/java/datadog/trace/tracer/SpanImpl.java similarity index 86% rename from dd-trace/src/main/java/datadog/trace/tracer/impl/SpanImpl.java rename to dd-trace/src/main/java/datadog/trace/tracer/SpanImpl.java index c002baf25e..fa4f622519 100644 --- a/dd-trace/src/main/java/datadog/trace/tracer/impl/SpanImpl.java +++ b/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() { diff --git a/dd-trace/src/main/java/datadog/trace/tracer/Trace.java b/dd-trace/src/main/java/datadog/trace/tracer/Trace.java index 6d2c2fcfee..1b764ffd07 100644 --- a/dd-trace/src/main/java/datadog/trace/tracer/Trace.java +++ b/dd-trace/src/main/java/datadog/trace/tracer/Trace.java @@ -6,6 +6,8 @@ package datadog.trace.tracer; * *
A trace will be written when all of its spans are finished and all trace continuations are * closed. + * + *
To create a Trace, see {@link Tracer#buildTrace()} */ public interface Trace { /** Get the tracer which created this trace. */ diff --git a/dd-trace/src/main/java/datadog/trace/tracer/impl/TraceImpl.java b/dd-trace/src/main/java/datadog/trace/tracer/TraceImpl.java similarity index 87% rename from dd-trace/src/main/java/datadog/trace/tracer/impl/TraceImpl.java rename to dd-trace/src/main/java/datadog/trace/tracer/TraceImpl.java index a978acb3bc..3295a58a8c 100644 --- a/dd-trace/src/main/java/datadog/trace/tracer/impl/TraceImpl.java +++ b/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 spans = null; + + /** + * Create a new Trace. + * + * @param tracer the Tracer to apply settings from. + */ + TraceImpl(Tracer tracer) {} } diff --git a/dd-trace/src/main/java/datadog/trace/tracer/Tracer.java b/dd-trace/src/main/java/datadog/trace/tracer/Tracer.java index a9b2b6e2b7..db363a2ff4 100644 --- a/dd-trace/src/main/java/datadog/trace/tracer/Tracer.java +++ b/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