Introduce ActiveSpan, ActiveSpan.Continuation, and ActiveSpanSource

README.md

@@ -18,6 +18,135 @@ to facilitate unit-testing of OpenTracing Java instrumentation.
 
 Packages are deployed to Maven Central under the `io.opentracing` group.
 
+## Usage
+
+### Initialization
+
+Initialization is OpenTracing-implementation-specific. Generally speaking, the pattern is to initialize a `Tracer` once for the entire process and to use that `Tracer` for the remainder of the process lifetime. The [GlobalTracer](https://github.com/opentracing/opentracing-java/blob/master/opentracing-util/src/main/java/io/opentracing/util/GlobalTracer.java) provides a helper for singleton access to the `Tracer`.
+
+### `ActiveSpan`s, `Continuation`s, and within-process prapagation
+
+For any Thread, at most one `Span` may be "active". Of course there may be many other `Spans` involved with the Thread which are (a) started, (b) not finished, and yet (c) not "active": perhaps they are waiting for I/O, blocked on a child Span, or otherwise off of the critical path.
+
+It's inconvenient to pass an active `Span` from function to function manually, so OpenTracing provides an `ActiveSpanSource` abstraction to grant access to an `ActiveSpan` and to pin and `capture()` it for re-activation in another Thread (e.g., in an async callback).
+
+Access to the active `Span` is straightforward:
+
+```
+io.opentracing.Tracer tracer = ...;
+...
+ActiveSpan span = tracer.activeSpan();
+if (span != null) {
+    span.log("...");
+}
+```
+
+### Starting a new Span
+
+The simplest case – which does not take advantage of `ActiveSpanSource` – looks like this:
+
+```
+io.opentracing.Tracer tracer = ...;
+...
+Span span = tracer.buildSpan("someWork").startManual();
+try {
+    // (do things / record data to `span`)
+} finally {
+    span.finish();
+}
+```
+
+Or, to take advantage of `ActiveSpanSource` and automatic intra-process propagation, like this:
+
+```
+io.opentracing.Tracer tracer = ...;
+...
+try (ActiveSpan activeSpan = tracer.buildSpan("someWork").startActive()) {
+    // Do things.
+    //
+    // If we create async work, `activeSpan.capture()` allows us to pass the `ActiveSpan` along as well.
+}
+```
+
+The above is semantically equivalent to the more explicit try-finally version:
+
+```
+io.opentracing.Tracer tracer = ...;
+...
+ActiveSpan activeSpan = tracer.buildSpan("someWork").startActive();
+try {
+    // Do things.
+} finally {
+    activeSpan.deactivate();
+}
+```
+
+
+**If there is an `ActiveSpan`, it will act as the parent to any newly started `Span`** unless the programmer invokes `ignoreActiveSpan()` at `buildSpan()` time, like so:
+
+```
+io.opentracing.Tracer tracer = ...;
+...
+ActiveSpan span = tracer.buildSpan("someWork").ignoreActiveSpan().startActive();
+```
+
+### Deferring asynchronous work
+
+Consider the case where a `Span`'s lifetime logically starts in one thread and ends in another. For instance, the intra-Span timing breakdown might look like this:
+
+```
+[ ServiceHandlerSpan                                 ]
+|-FunctionA-|-----waiting on an RPC------|-FunctionB-|
+
+------------------------------------------------> time
+```
+
+The `"ServiceHandlerSpan"` is _active_ when it's running FunctionA and FunctionB, and inactive while it's waiting on an RPC (presumably modelled as its own Span, though that's not the concern here).
+
+**The `ActiveSpanSource` makes it easy to `capture()` the Span and execution context in `FunctionA` and re-activate it in `FunctionB`.** Note that every `Tracer` must also implement `ActiveSpanSource`. These are the steps:
+
+1. Start the `ActiveSpan` via `Tracer.startActive()` rather than via `Tracer.startManual()`; or, if the `Span` was already started manually via `startManual()`, call `ActiveSpanSource#makeActive(span)`. Either route will yield an `ActiveSpan` instance that encapsulates the `Span`.
+2. In the method/function that *allocates* the closure/`Runnable`/`Future`/etc, call `ActiveSpan#capture()` to obtain an `ActiveSpan.Continuation`
+3. In the closure/`Runnable`/`Future`/etc itself, invoke `ActiveSpan.Continuation#activate` to re-activate the `ActiveSpan`, then `deactivate()` it when the Span is no longer active (or use try-with-resources for less typing).
+
+For example:
+
+```
+io.opentracing.Tracer tracer = ...;
+...
+// STEP 1 ABOVE: start the ActiveSpan
+try (ActiveSpan serviceSpan = tracer.buildSpan("ServiceHandlerSpan").startActive()) {
+    ...
+
+    // STEP 2 ABOVE: capture the ActiveSpan
+    final ActiveSpan.Continuation cont = serviceSpan.capture();
+    doAsyncWork(new Runnable() {
+        @Override
+        public void run() {
+
+            // STEP 3 ABOVE: use the Continuation to reactivate the Span in the callback.
+            try (ActiveSpan activeSpan = cont.activate()) {
+                ...
+            }
+        }
+    });
+}
+```
+
+In practice, all of this is most fluently accomplished through the use of an OpenTracing-aware `ExecutorService` and/or `Runnable`/`Callable` adapter; they can factor most of the typing.
+
+#### Automatic `finish()`ing via `ActiveSpan` reference counts
+
+When an `ActiveSpan` is created (either via `Tracer.SpanBuilder#startActive` or `ActiveSpanSource#makeActive(Span)`), the reference count associated with the `ActiveSpan` is `1`.
+
+- When an `ActiveSpan.Continuation` is created via `ActiveSpan#capture`, the reference count **increments**
+- When an `ActiveSpan.Continuation` is `ActiveSpan.Continuation#activate()`d and thus transformed back into an `ActiveSpan`, the reference count **is unchanged**
+- When an `ActiveSpan` is `ActiveSpan#deactivate()`d, the reference count **decrements**
+
+When the reference count decrements to zero, **the `Span`'s `finish()` method is invoked automatically.**
+
+When used as designed, the programmer should not need to invoke `Span#finish()` manually, but rather should let `ActiveSpan` and `ActiveSpan.Continuation` invoke `finish()` as soon as the last active or deferred `ActiveSpan` is deactivated.
+
 # Development
 
 This is a maven project, and provides a wrapper, `./mvnw` to pin a consistent

opentracing-api/src/main/java/io/opentracing/ActiveSpan.java

@@ -0,0 +1,96 @@
+/**
+ * Copyright 2016-2017 The OpenTracing Authors
+ *
+ * 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 io.opentracing;
+
+import java.io.Closeable;
+
+/**
+ * In any execution context (or any thread, etc), there is at most one "active" {@link Span}/{@link ActiveSpan}
+ * primarily responsible for the work accomplished by the surrounding application code. That {@link ActiveSpan} may be
+ * accessed via the {@link ActiveSpanSource#activeSpan()} method. If the application needs to capture work that should
+ * be part of the same Span, the Source provides a {@link ActiveSpan#capture} method that returns a
+ * {@link Continuation}; this continuation may be used to re-activate and continue the {@link Span} in that other
+ * asynchronous executor and/or thread.
+ *
+ * <p>
+ * {@link ActiveSpan}s are created via {@link Tracer.SpanBuilder#startActive()} or {@link ActiveSpanSource#makeActive}.
+ * They can be {@link ActiveSpan#capture()}ed as {@link ActiveSpan.Continuation}s, then
+ * re-{@link Continuation#activate()}d later.
+ *
+ * <p>
+ * NOTE: {@link ActiveSpan} extends {@link Closeable} rather than {@code AutoCloseable} in order to keep support
+ * for JDK1.6.
+ *
+ * @see ActiveSpanSource
+ */
+public interface ActiveSpan extends Closeable, Span {
+    /**
+     * Mark the end of the active period for the {@link Span} pinned by this {@link ActiveSpan}. When the last
+     * {@link ActiveSpan} is deactivated for a given {@link Span}, it is automatically {@link Span#finish()}ed.
+     * <p>
+     * NOTE: Calling {@link #deactivate} more than once on a single {@link ActiveSpan} instance is undefined behavior.
+     *
+     * @see Closeable#close() {@link ActiveSpan}s are auto-closeable and may be used in try-with-resources blocks
+     */
+    void deactivate();
+
+    /**
+     * A synonym for {@link #deactivate()} that can be used in try-with-resources blocks.
+     */
+    @Override
+    void close();
+
+    /**
+     * "Capture" a new {@link Continuation} associated with this {@link ActiveSpan} and {@link Span}, as well as any
+     * 3rd-party execution context of interest.
+     *
+     * <p>
+     * <em>IMPORTANT:</em> the caller MUST {@link Continuation#activate()} and {@link ActiveSpan#deactivate()} the
+     * returned {@link Continuation} or the pinned {@link Span} will never automatically {@link Span#finish()}. That is,
+     * calling {@link #capture()} increments a refcount that must be decremented somewhere else.
+     *
+     * <p>
+     * The associated {@link Span} will not {@link Span#finish()} while a {@link Continuation} is outstanding; in
+     * this way, it provides a reference/pin just like an {@link ActiveSpan} does.
+     *
+     * @return a new {@link Continuation} to {@link Continuation#activate()} at the appropriate time.
+     */
+    Continuation capture();
+
+    /**
+     * A {@link Continuation} can be used *once* to activate a Span along with any non-OpenTracing execution context
+     * (e.g., MDC), then deactivate when processing activity moves on to another Span. (In practice, this active
+     * period typically extends for the length of a deferred async closure invocation.)
+     *
+     * <p>
+     * Most users do not directly interact with {@link Continuation}, {@link Continuation#activate()} or
+     * {@link ActiveSpan#deactivate()}, but rather use {@link ActiveSpanSource}-aware Runnables/Callables/Executors.
+     * Those higher-level primitives need not be defined within the OpenTracing core API, and so they are not.
+     *
+     * @see ActiveSpanSource#makeActive(Span)
+     */
+    interface Continuation {
+        /**
+         * Make the Span (and other execution context) encapsulated by this Continuation active and return it.
+         *
+         * <p>
+         * NOTE: It is an error to call activate() more than once on a single Continuation instance.
+         *
+         * @see ActiveSpanSource#makeActive(Span)
+         * @return a handle to the newly-activated Span
+         */
+        ActiveSpan activate();
+    }
+
+}

opentracing-api/src/main/java/io/opentracing/ActiveSpanSource.java

@@ -0,0 +1,39 @@
+/**
+ * Copyright 2016-2017 The OpenTracing Authors
+ *
+ * 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 io.opentracing;
+
+/**
+ * {@link ActiveSpanSource} allows an existing (possibly thread-local-aware) execution context provider to act as a
+ * source for an actively-scheduled OpenTracing Span.
+ *
+ * @see ActiveSpan
+ */
+public interface ActiveSpanSource {
+
+    /**
+     * @return the {@link ActiveSpan active span}, or null if none could be found. This does not affect the reference
+     * count for the {@link ActiveSpan}.
+     */
+    ActiveSpan activeSpan();
+
+    /**
+     * Wrap and "makeActive" a {@link Span} by encapsulating it – and any active state (e.g., MDC state) in the
+     * execution context – in a new {@link ActiveSpan}.
+     *
+     * @param span the Span just started
+     * @return an {@link ActiveSpan} that encapsulates the given Span and any other Source-specific context (e.g.,
+     * MDC data)
+     */
+    ActiveSpan makeActive(Span span);
+}

opentracing-api/src/main/java/io/opentracing/Span.java

@@ -1,5 +1,5 @@
 /**
- * Copyright 2016 The OpenTracing Authors
+ * Copyright 2016-2017 The OpenTracing Authors
  *
  * 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
@@ -21,7 +21,7 @@
  *
  * <p>Spans are created by the {@link Tracer#buildSpan} interface.
  */
-public interface Span extends Closeable {
+public interface Span {
     /**
      * Retrieve the associated SpanContext.
      *
@@ -34,8 +34,9 @@ public interface Span extends Closeable {
     /**
      * Sets the end timestamp to now and records the span.
      *
-     * <p>With the exception of calls to Span.context(), this should be the last call made to the span instance, and to
-     * do otherwise leads to undefined behavior.
+     * <p>With the exception of calls to {@link #context}, this should be the last call made to the span instance.
+     * Future calls to {@link #finish} are defined as noops, and future calls to methods other than {@link #context}
+     * lead to undefined behavior.
      *
      * @see Span#context()
      */
@@ -53,8 +54,6 @@ public interface Span extends Closeable {
      */
     void finish(long finishMicros);
 
-    void close();
-
     /**
      * Set a key:value tag on the Span.
      */
@@ -74,14 +73,14 @@ public interface Span extends Closeable {
      * Caveat emptor.
      *
      * <p>A contrived example (using Guava, which is not required):
-     * <pre>{@code
-     span.log(
-         ImmutableMap.Builder<String, Object>()
-         .put("event", "soft error")
-         .put("type", "cache timeout")
-         .put("waited.millis", 1500)
-         .build());
-     }</pre>
+     * <pre><code>
+       span.log(
+           ImmutableMap.Builder<String, Object>()
+           .put("event", "soft error")
+           .put("type", "cache timeout")
+           .put("waited.millis", 1500)
+           .build());
+       </code></pre>
      *
      * @param fields key:value log fields. Tracer implementations should support String, numeric, and boolean values;
      *               some may also support arbitrary Objects.
@@ -110,9 +109,9 @@ public interface Span extends Closeable {
      *
      * Shorthand for
      *
-     * <pre>{@code
-     span.log(Collections.singletonMap("event", event));
-     }</pre>
+     * <pre><code>
+       span.log(Collections.singletonMap("event", event));
+       </code></pre>
      *
      * @param event the event value; often a stable identifier for a moment in the Span lifecycle
      * @return the Span, for chaining
@@ -124,9 +123,9 @@ public interface Span extends Closeable {
      *
      * Shorthand for
      *
-     * <pre>{@code
-     span.log(timestampMicroseconds, Collections.singletonMap("event", event));
-     }</pre>
+     * <pre><code>
+       span.log(timestampMicroseconds, Collections.singletonMap("event", event));
+       </code></pre>
      *
      * @param timestampMicroseconds The explicit timestamp for the log record. Must be greater than or equal to the
      *                              Span's start timestamp.