Merge branch 'v0.32.0' into tyler/withtag

opentracing-api/pom.xml

@@ -20,7 +20,7 @@
     <parent>
         <groupId>io.opentracing</groupId>
         <artifactId>parent</artifactId>
-        <version>0.31.1-SNAPSHOT</version>
+        <version>0.32.0-SNAPSHOT</version>
     </parent>
 
     <artifactId>opentracing-api</artifactId>

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

@@ -26,8 +26,9 @@
  */
 public interface Scope extends Closeable {
     /**
-     * Mark the end of the active period for the current thread and {@link Scope},
-     * updating the {@link ScopeManager#active()} in the process.
+     * Mark the end of the active period for the current context (usually a thread)
+     * and {@link Scope}, updating {@link ScopeManager#active()} and {@link ScopeManager#activeSpan()}
+     * in the process.
      *
      * <p>
      * NOTE: Calling {@link #close} more than once on a single {@link Scope} instance leads to undefined
@@ -37,7 +38,11 @@ public interface Scope extends Closeable {
     void close();
 
     /**
+     * @deprecated use {@link Span} directly or access it through {@link ScopeManager#activeSpan()}
+     * Return the corresponding active {@link Span} for this instance.
+     *
      * @return the {@link Span} that's been scoped by this {@link Scope}
      */
+    @Deprecated
     Span span();
 }

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

@@ -26,26 +26,92 @@
 public interface ScopeManager {
 
     /**
-     * Make a {@link Span} instance active.
+     * Set the specified {@link Span} as the active instance for the current
+     * context (usually a thread).
      *
-     * @param span the {@link Span} that should become the {@link #active()}
-     * @param finishSpanOnClose whether span should automatically be finished when {@link Scope#close()} is called
+     * <p>
+     * The returned {@link Scope} represents the active state for the span.
+     * Once its active period is due, {@link Scope#close()} ought to be called.
+     * To ease this operation, {@link Scope} supports try-with-resources.
+     * Observe the span will not be automatically finished when {@link Scope#close()}
+     * is called.
+     *
+     * <p>
+     * This {@link Scope} instance can be accessed at any time through {@link #active()},
+     * in case it is not possible for the user to store it (when used through middleware
+     * or start/finish event hooks, for example). The corresponding {@link Span} can be
+     * accessed through {@link #activeSpan()} likewise.
+     *
+     * <p>
+     * Usage:
+     * <pre><code>
+     *     Span span = tracer.buildSpan("...").start();
+     *     try (Scope scope = tracer.scopeManager().activate(span)) {
+     *         span.setTag("...", "...");
+     *         ...
+     *     } catch (Exception e) {
+     *         span.log(...);
+     *     } finally {
+     *         // Optionally finish the Span if the operation it represents
+     *         // is logically completed at this point.
+     *         span.finish();
+     *     }
+     * </code></pre>
+     *
+     * @param span the {@link Span} that should become the {@link #activeSpan()}
      * @return a {@link Scope} instance to control the end of the active period for the {@link Span}. It is a
      * programming error to neglect to call {@link Scope#close()} on the returned instance.
      */
-    Scope activate(Span span, boolean finishSpanOnClose);
+    Scope activate(Span span);
 
     /**
-     * Return the currently active {@link Scope} which can be used to access the currently active
-     * {@link Scope#span()}.
+     * Return the currently active {@link Scope} which can be used to deactivate the currently active
+     * {@link Span}.
+     *
+     * <p>
+     * Observe that {@link Scope} is expected to be used only in the same thread where it was
+     * created, and thus should not be passed across threads.
      *
      * <p>
-     * If there is an {@link Scope non-null scope}, its wrapped {@link Span} becomes an implicit parent
-     * (as {@link References#CHILD_OF} reference) of any
-     * newly-created {@link Span} at {@link Tracer.SpanBuilder#startActive(boolean)} or {@link SpanBuilder#start()}
-     * time rather than at {@link Tracer#buildSpan(String)} time.
+     * Because both {@link #active()} and {@link #activeSpan()} reference the current
+     * active state, they both will be either null or non-null.
      *
      * @return the {@link Scope active scope}, or null if none could be found.
      */
     Scope active();
+
+    /**
+     * Return the currently active {@link Span}.
+     *
+     * <p>
+     * Because both {@link #active()} and {@link #activeSpan()} reference the current
+     * active state, they both will be either null or non-null.
+     *
+     * @return the {@link Span active span}, or null if none could be found.
+     */
+    Span activeSpan();
+
+    /**
+     * @deprecated use {@link #activate(Span)} instead.
+     * Set the specified {@link Span} as the active instance for the current
+     * context (usually a thread).
+     *
+     * <p>
+     * Finishing the {@link Span} upon {@link Scope#close()} is discouraged,
+     * as reporting errors becomes impossible:
+     * <pre><code>
+     *     try (Scope scope = tracer.scopeManager().activate(span, true)) {
+     *     } catch (Exception e) {
+     *         // Not possible to report errors, as
+     *         // the span has been already finished.
+     *     }
+     * </code></pre>
+     *
+     * @param span the {@link Span} that should become the {@link #activeSpan()}
+     * @param finishSpanOnClose whether span should automatically be finished when {@link Scope#close()} is called
+     * @return a {@link Scope} instance to control the end of the active period for the {@link Span}. It is a
+     * programming error to neglect to call {@link Scope#close()} on the returned instance.
+     */
+    @Deprecated
+    Scope activate(Span span, boolean finishSpanOnClose);
 }

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

@@ -26,6 +26,30 @@
  * @see Span#getBaggageItem(String)
  */
 public interface SpanContext {
+    /**
+     * Return the ID of the trace.
+     *
+     * Should be globally unique. Every span in a trace shares this ID.
+     *
+     * An empty String will be returned if the tracer does not support this functionality
+     * (this is the case for no-op tracers, for example). null is an invalid return value.
+     *
+     * @return the trace ID for this context.
+     */
+    String toTraceId();
+
+    /**
+     * Return the ID of the associated Span.
+     *
+     * Should be unique within a trace. Each span within a trace contains a different ID.
+     *
+     * An empty String will be returned if the tracer does not support this functionality
+     * (this is the case for no-op tracers, for example). null is an invalid return value.
+     *
+     * @return the Span ID for this context.
+     */
+    String toSpanId();
+
     /**
      * @return all zero or more baggage items propagating along with the associated Span
      *

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

@@ -27,11 +27,20 @@ public interface Tracer {
     ScopeManager scopeManager();
 
     /**
-     * @return the active {@link Span}. This is a shorthand for Tracer.scopeManager().active().span(),
-     * and null will be returned if {@link Scope#active()} is null.
+     * @return the active {@link Span}. This is a shorthand for {@code Tracer.scopeManager().activeSpan()}.
      */
     Span activeSpan();
 
+    /**
+     * Make a {@link Span} instance active for the current context (usually a thread).
+     * This is a shorthand for {@code Tracer.scopeManager().activate(span)}.
+     *
+     * @return a {@link Scope} instance to control the end of the active period for the {@link Span}. It is a
+     * programming error to neglect to call {@link Scope#close()} on the returned instance,
+     * and it may lead to memory leaks as the {@link Scope} may remain in the thread-local stack.
+     */
+    Scope activateSpan(Span span);
+
     /**
      * Return a new SpanBuilder for a Span with the given `operationName`.
      *
@@ -41,19 +50,21 @@ public interface Tracer {
      * <pre><code>
      *   Tracer tracer = ...
      *
-     *   // Note: if there is a `tracer.active()` Scope, its `span()` will be used as the target
-     *   // of an implicit CHILD_OF Reference for "workScope.span()" when `startActive()` is invoked.
-     *   try (Scope workScope = tracer.buildSpan("DoWork").startActive()) {
-     *       workScope.span().setTag("...", "...");
-     *       // etc, etc
-     *   }
-     *
-     *   // It's also possible to create Spans manually, bypassing the ScopeManager activation.
-     *   Span http = tracer.buildSpan("HandleHTTPRequest")
+     *   // Note: if there is a `tracer.activeSpan()` instance, it will be used as the target
+     *   // of an implicit CHILD_OF Reference when `start()` is invoked,
+     *   // unless another Span reference is explicitly provided to the builder.
+     *   Span span = tracer.buildSpan("HandleHTTPRequest")
      *                     .asChildOf(rpcSpanContext)  // an explicit parent
      *                     .withTag("user_agent", req.UserAgent)
      *                     .withTag("lucky_number", 42)
      *                     .start();
+     *   span.setTag("...", "...");
+     *
+     *   // It is possible to set the Span as the active instance for the current context
+     *   // (usually a thread).
+     *   try (Scope scope = tracer.activateSpan(span)) {
+     *      ...
+     *   }
      * </code></pre>
      */
     SpanBuilder buildSpan(String operationName);
@@ -88,7 +99,7 @@ public interface Tracer {
      * Tracer tracer = ...
      * TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
      * SpanContext spanCtx = tracer.extract(Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
-     * ... = tracer.buildSpan('...').asChildOf(spanCtx).startActive();
+     * ... = tracer.buildSpan('...').asChildOf(spanCtx).start();
      * </code></pre>
      *
      * If the span serialized state is invalid (corrupt, wrong version, etc) inside the carrier this will result in an
@@ -170,55 +181,70 @@ interface SpanBuilder {
         SpanBuilder withStartTimestamp(long microseconds);
 
         /**
-         * Returns a newly started and activated {@link Scope}.
-         *
-         * <p>
-         * The returned {@link Scope} supports try-with-resources. For example:
-         * <pre><code>
-         *     try (Scope scope = tracer.buildSpan("...").startActive(true)) {
-         *         // (Do work)
-         *         scope.span().setTag( ... );  // etc, etc
-         *     }
-         *     // Span does finishes automatically only when 'finishSpanOnClose' is true
-         * </code></pre>
+         * @deprecated use {@link #start} instead.
+         */
+        @Deprecated
+        Span startManual();
+
+        /**
+         * Returns a newly-started {@link Span}.
          *
          * <p>
          * If
          * <ul>
-         * <li>the {@link Tracer}'s {@link ScopeManager#active()} is not null, and
+         * <li>the {@link Tracer}'s {@link ScopeManager#activeSpan()} is not null, and
          * <li>no <b>explicit</b> references are added via {@link SpanBuilder#addReference}, and
          * <li>{@link SpanBuilder#ignoreActiveSpan()} is not invoked,
          * </ul>
          * ... then an inferred {@link References#CHILD_OF} reference is created to the
-         * {@link ScopeManager#active()}'s {@link SpanContext} when either
+         * {@link ScopeManager#activeSpan()}'s {@link SpanContext} when either
          * {@link SpanBuilder#start()} or {@link SpanBuilder#startActive} is invoked.
+
+         * @return the newly-started Span instance, which has *not* been automatically registered
+         *         via the {@link ScopeManager}
+         */
+        Span start();
+
+        /**
+         * @deprecated use {@link #start()} and {@link ScopeManager#activate(Span span)} instead.
+         * Returns a newly started and activated {@link Scope}.
+         *
+         * <p>
+         * {@link SpanBuilder#startActive()} is a shorthand for
+         * {@code tracer.scopeManager().activate(spanBuilder.start())}.
+         * The returned {@link Scope} supports try-with-resources, but using this method is
+         * discouraged as the {@link Span} reference could be easily lost, and reporting
+         * errors on {@link Span} through this method becomes impossible:
+         * <pre><code>
+         *     try (Scope scope = tracer.buildSpan("...").startActive(true)) {
+         *         // (Do work)
+         *         scope.span().setTag( ... );  // etc, etc
+         *     } catch (Exception e) {
+         *         // Not possible to report errors, as
+         *         // the span reference has been lost,
+         *         // and span has been already finished too.
+         *     }
+         * </code></pre>
          *
          * <p>
-         * Note: {@link SpanBuilder#startActive(boolean)} is a shorthand for
-         * {@code tracer.scopeManager().activate(spanBuilder.start(), finishSpanOnClose)}.
+         * It is recommended to use {@link #start()} with a subsequent call to
+         * {@link ScopeManager#activate(Span)}
+         * <pre><code>
+         *     Span span = tracer.buildSpan("...").start();
+         *     try (Scope scope = tracer.activateSpan(span)) {
+         *     } catch (Exception e) {
+         *         span.log(...); // Report any errors properly.
+         *     } finally {
+         *         span.finish(); // Optionally close the Span.
+         *     }
+         * </code></pre>
          *
-         * @param finishSpanOnClose whether span should automatically be finished when {@link Scope#close()} is called
          * @return a {@link Scope}, already registered via the {@link ScopeManager}
          *
          * @see ScopeManager
          * @see Scope
          */
-        Scope startActive(boolean finishSpanOnClose);
-
-        /**
-         * @deprecated use {@link #start} or {@link #startActive} instead.
-         */
         @Deprecated
-        Span startManual();
-
-        /**
-         * Like {@link #startActive()}, but the returned {@link Span} has not been registered via the
-         * {@link ScopeManager}.
-         *
-         * @see SpanBuilder#startActive(boolean)
-         * @return the newly-started Span instance, which has *not* been automatically registered
-         *         via the {@link ScopeManager}
-         */
-        Span start();
+        Scope startActive(boolean finishSpanOnClose);
     }
 }

opentracing-api/src/main/java/io/opentracing/propagation/Binary.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2016-2018 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.propagation;
+
+import java.nio.ByteBuffer;
+
+/**
+ * Binary is an interface defining the required operations for a binary carrier for
+ * Tracer.inject() and Tracer.extract(). Binary can be defined either as inbound (extraction)
+ * or outbound (injection).
+ *
+ * When Binary is defined as inbound, extractionBuffer() will be called to retrieve the ByteBuffer
+ * containing the data used for SpanContext extraction.
+ *
+ * When Binary is defined as outbound, setInjectBufferLength() will be called in order to hint
+ * the required buffer length to inject the SpanContext, and injectionBuffer() will be called
+ * afterwards to retrieve the actual ByteBuffer used for the SpanContext injection.
+ *
+ * @see Format.Builtin#BINARY
+ * @see io.opentracing.Tracer#inject(SpanContext, Format, Object)
+ * @see io.opentracing.Tracer#extract(Format, Object)
+ */
+public interface Binary {
+    /**
+     * Gets the buffer used to store data as part of {@link SpanContext} injection.
+     *
+     * The lenght parameter hints the buffer length required for
+     * {@link SpanContext} injection. The user may use this to allocate a new
+     * ByteBuffer or resize an existing one.
+     *
+     * It is an error to call this method when Binary is used
+     * for {@link SpanContext} extraction.
+     *
+     * @param length The buffer length required for {@link SpanContext} injection.
+     *               It needs to be larger than zero.
+     *
+     * @return The buffer used for {@link SpanContext} injection.
+     */
+    ByteBuffer injectionBuffer(int lenght);
+
+    /**
+     * Gets the buffer containing the data used for {@link SpanContext} extraction.
+     *
+     * It is an error to call this method when Binary is used
+     * for {@link SpanContext} injection.
+     *
+     * @return The buffer used for {@link SpanContext} extraction.
+     */
+    ByteBuffer extractionBuffer();
+}