SpanManager POC

opentracing-api/pom.xml

@@ -29,8 +29,8 @@
 
     <properties>
         <main.basedir>${project.basedir}/..</main.basedir>
-        <main.java.version>1.6</main.java.version>
-        <main.signature.artifact>java16</main.signature.artifact>
+        <main.java.version>1.7</main.java.version>
+        <main.signature.artifact>java17</main.signature.artifact>
     </properties>
 
     <dependencies>
@@ -40,5 +40,20 @@
             <version>1.10.19</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+            <version>1.7.23</version>
+        </dependency>
+        <dependency>
+            <groupId>log4j</groupId>
+            <artifactId>log4j</artifactId>
+            <version>1.2.17</version>
+        </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-log4j12</artifactId>
+            <version>1.7.23</version>
+        </dependency>
     </dependencies>
 </project>

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

@@ -0,0 +1,78 @@
+package io.opentracing;
+
+/**
+ * SpanManager allows an existing (possibly thread-local-aware) execution context provider to also manage the current
+ * active OpenTracing span.
+ */
+public interface SpanManager {
+
+    /**
+     * A SpanClosure can be used *once* to make a Span active within a SpanManager, then deactivate it once the
+     * "closure" (or period of Span activity) has finished.
+     *
+     * Most users do not directly interact with SpanClosure, activate(), or deactivate(), but rather use
+     * SpanManager-aware Runnables/Callables/Executors. Those higher-level primitives need not be defined within the
+     * OpenTracing core API.
+     *
+     * @see SpanManager#captureActive()
+     */
+    interface SpanClosure extends AutoCloseable {
+
+        /**
+         * Make the Span encapsulated by this SpanClosure active and return it.
+         *
+         * NOTE: It is an error to call activate() more than once on a single SpanClosure instance.
+         *
+         * @see SpanManager#captureActive()
+         * @return the newly-activated Span
+         */
+        Span activate();
+
+        /**
+         * @return the encapsulated Span, or null if there isn't one.
+         */
+        Span span();
+
+        /**
+         * End this active period for the Span previously returned by activate(). Finish the span iff finish=true.
+         *
+         * NOTE: It is an error to call deactivate() more than once on a single SpanClosure instance.
+         */
+        void deactivate(boolean finishSpan);
+
+    }
+
+    /**
+     * @return the currently active Span for this SpanManager, or null if no such Span could be found
+     */
+    Span active();
+
+     /**
+     * Capture any SpanManager-specific context (e.g., MDC context) along with the active Span (even if null) and
+     * encapsulate it in a SpanClosure for activation in the future, perhaps in a different thread or on a different
+     * executor.
+     *
+     * If the active Span is null, the implementation must still return a valid SpanClosure; when the closure activates,
+     * it will clear any active Span.
+     *
+     * @see SpanManager.SpanClosure
+     *
+     * @return a SpanClosure that represents the active Span and any other SpanManager-specific context, even if the
+     *     active Span is null.
+     */
+    SpanClosure captureActive();
+
+    /**
+     * Explicitly capture the given Span and any active state (e.g., MDC state) about the current execution context.
+     *
+     * @param span
+     * @return a SpanClosure that represents the active Span and any other SpanManager-specific context, even if the
+     *     active Span is null.
+     */
+    SpanClosure capture(Span span);
+
+    /**
+     * Tell the SpanManager that a particular Span has finished (and update any structures accordingly).
+     */
+    void onFinish(Span span);
+}

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

@@ -23,6 +23,9 @@ public interface Tracer {
   /**
    * Return a new SpanBuilder for a Span with the given `operationName`.
    *
+   * <p>If there is an active Span according to the activeSpanManager(),
+   * buildSpan will automatically have an asChildOf() reference to same.
+   *
    * <p>You can override the operationName later via {@link Span#setOperationName(String)}.
    *
    * <p>A contrived example:
@@ -41,6 +44,8 @@ public interface Tracer {
    */
   SpanBuilder buildSpan(String operationName);
 
+  SpanManager activeSpanManager();
+
   /**
    * Inject a SpanContext into a `carrier` of a given type, presumably for propagation across process boundaries.
    *
@@ -128,5 +133,7 @@ interface SpanBuilder extends SpanContext {
       /** Returns the started Span. */
       Span start();
 
+      SpanManager.SpanClosure startAndActivate();
+
   }
 }

opentracing-api/src/main/java/io/opentracing/propagation/Format.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
@@ -35,6 +35,12 @@
  */
 public interface Format<C> {
     final class Builtin<C> implements Format<C> {
+        private final String name;
+
+        private Builtin(String name) {
+            this.name = name;
+        }
+
         /**
          * The TEXT_MAP format allows for arbitrary String->String map encoding of SpanContext state for Tracer.inject
          * and Tracer.extract.
@@ -46,7 +52,7 @@ final class Builtin<C> implements Format<C> {
          * @see Format
          * @see Builtin#HTTP_HEADERS
          */
-        public final static Format<TextMap> TEXT_MAP = new Builtin<TextMap>();
+        public final static Format<TextMap> TEXT_MAP = new Builtin<TextMap>("TEXT_MAP");
 
         /**
          * The HTTP_HEADERS format allows for HTTP-header-compatible String->String map encoding of SpanContext state
@@ -60,7 +66,7 @@ final class Builtin<C> implements Format<C> {
          * @see Format
          * @see Builtin#TEXT_MAP
          */
-        public final static Format<TextMap> HTTP_HEADERS = new Builtin<TextMap>();
+        public final static Format<TextMap> HTTP_HEADERS = new Builtin<TextMap>("HTTP_HEADERS");
 
         /**
          * The BINARY format allows for unconstrained binary encoding of SpanContext state for Tracer.inject and
@@ -70,6 +76,14 @@ final class Builtin<C> implements Format<C> {
          * @see io.opentracing.Tracer#extract(Format, Object)
          * @see Format
          */
-        public final static Format<ByteBuffer> BINARY = new Builtin<ByteBuffer>();
+        public final static Format<ByteBuffer> BINARY = new Builtin<ByteBuffer>("BINARY");
+
+        /**
+         * @return Short name for built-in formats as they tend to show up in exception messages.
+         */
+        @Override
+        public String toString() {
+            return Builtin.class.getSimpleName() + "." + name;
+        }
     }
 }

opentracing-api/src/main/java/io/opentracing/tag/Tags.java

@@ -22,11 +22,12 @@
  */
 
 public final class Tags {
-    private Tags(){}
+    private Tags() {
+    }
 
     /**
-    * A constant for setting the span kind to indicate that it represents a server span.
-    */
+     * A constant for setting the span kind to indicate that it represents a server span.
+     */
     public static final String SPAN_KIND_SERVER = "server";
 
     /**
@@ -35,32 +36,32 @@ private Tags(){}
     public static final String SPAN_KIND_CLIENT = "client";
 
     /**
-     *  HTTP_URL records the url of the incoming request.
+     * HTTP_URL records the url of the incoming request.
      */
     public static final StringTag HTTP_URL = new StringTag("http.url");
 
     /**
-     *  HTTP_STATUS records the http status code of the response.
+     * HTTP_STATUS records the http status code of the response.
      */
     public static final IntTag HTTP_STATUS = new IntTag("http.status_code");
 
     /**
-     *  HTTP_METHOD records the http method. Case-insensitive.
+     * HTTP_METHOD records the http method. Case-insensitive.
      */
     public static final StringTag HTTP_METHOD = new StringTag("http.method");
 
     /**
-     *  PEER_HOST_IPV4 records IPv4 host address of the peer.
+     * PEER_HOST_IPV4 records IPv4 host address of the peer.
      */
     public static final IntTag PEER_HOST_IPV4 = new IntTag("peer.ipv4");
 
     /**
-     *  PEER_HOST_IPV6 records the IPv6 host address of the peer.
+     * PEER_HOST_IPV6 records the IPv6 host address of the peer.
      */
     public static final StringTag PEER_HOST_IPV6 = new StringTag("peer.ipv6");
 
     /**
-     *  PEER_SERVICE records the service name of the peer.
+     * PEER_SERVICE records the service name of the peer.
      */
     public static final StringTag PEER_SERVICE = new StringTag("peer.service");
 
@@ -70,27 +71,50 @@ private Tags(){}
     public static final StringTag PEER_HOSTNAME = new StringTag("peer.hostname");
 
     /**
-     *  PEER_PORT records the port number of the peer.
+     * PEER_PORT records the port number of the peer.
      */
     public static final ShortTag PEER_PORT = new ShortTag("peer.port");
 
     /**
-     *  SAMPLING_PRIORITY determines the priority of sampling this Span.
+     * SAMPLING_PRIORITY determines the priority of sampling this Span.
      */
     public static final ShortTag SAMPLING_PRIORITY = new ShortTag("sampling.priority");
 
     /**
-     *  SPAN_KIND hints at the relationship between spans, e.g. client/server.
+     * SPAN_KIND hints at the relationship between spans, e.g. client/server.
      */
     public static final StringTag SPAN_KIND = new StringTag("span.kind");
 
     /**
-     *  COMPONENT is a low-cardinality identifier of the module, library, or package that is instrumented.
+     * COMPONENT is a low-cardinality identifier of the module, library, or package that is instrumented.
      */
-    public static final StringTag COMPONENT  = new StringTag("component");
+    public static final StringTag COMPONENT = new StringTag("component");
 
     /**
      * ERROR indicates whether a Span ended in an error state.
      */
     public static final BooleanTag ERROR = new BooleanTag("error");
+
+    /**
+     * DB_TYPE indicates the type of Database.
+     * For any SQL database, "sql". For others, the lower-case database category, e.g. "cassandra", "hbase", or "redis"
+     */
+    public static final StringTag DB_TYPE = new StringTag("db.type");
+
+    /**
+     * DB_INSTANCE indicates the instance name of Database.
+     * If the jdbc.url="jdbc:mysql://127.0.0.1:3306/customers", instance name is "customers".
+     */
+    public static final StringTag DB_INSTANCE = new StringTag("db.instance");
+
+    /**
+     * DB_USER indicates the user name of Database, e.g. "readonly_user" or "reporting_user"
+     */
+    public static final StringTag DB_USER = new StringTag("db.user");
+
+    /**
+     * DB_STATEMENT records a database statement for the given database type.
+     * For db.type="SQL", "SELECT * FROM wuser_table". For db.type="redis", "SET mykey "WuValue".
+     */
+    public static final StringTag DB_STATEMENT = new StringTag("db.statement");
 }

opentracing-api/src/test/java/io/opentracing/propagation/BuiltinFormatTest.java

@@ -0,0 +1,37 @@
+/**
+ * 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.propagation;
+
+import org.junit.Test;
+
+import static org.junit.Assert.assertEquals;
+
+public class BuiltinFormatTest {
+
+    @Test
+    public void test_HTTP_HEADERS_toString() {
+        assertEquals("Builtin.HTTP_HEADERS", Format.Builtin.HTTP_HEADERS.toString());
+    }
+
+    @Test
+    public void test_TEXT_MAP_toString() {
+        assertEquals("Builtin.TEXT_MAP", Format.Builtin.TEXT_MAP.toString());
+    }
+
+    @Test
+    public void test_BINARY_toString() {
+        assertEquals("Builtin.BINARY", Format.Builtin.BINARY.toString());
+    }
+
+}

opentracing-impl/src/main/java/io/opentracing/impl/AbstractSpan.java

@@ -23,6 +23,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicLong;
 
 abstract class AbstractSpan implements Span, SpanContext {
 
@@ -34,6 +35,7 @@ abstract class AbstractSpan implements Span, SpanContext {
     private Duration duration;
     private final Map<String,Object> tags = new HashMap<>();
     private final List<LogData> logs = new ArrayList<>();
+    private final AtomicLong refCount = new AtomicLong(0);  // XXX
 
     AbstractSpan(String operationName ) {
         this(operationName, Instant.now());

opentracing-impl/src/main/java/io/opentracing/impl/AbstractSpanBuilder.java

@@ -13,10 +13,8 @@
  */
 package io.opentracing.impl;
 
-import io.opentracing.References;
-import io.opentracing.Span;
-import io.opentracing.SpanContext;
-import io.opentracing.Tracer;
+import io.opentracing.*;
+
 import java.time.Instant;
 import java.util.ArrayList;
 import java.util.HashMap;
@@ -122,6 +120,11 @@ public final Span start() {
         return span;
     }
 
+    @Override
+    public SpanManager.SpanClosure startAndActivate() {
+        return null;  // XXX: not correct... we'd need access to the AbstractTracer's SpanManager.
+    }
+
     private void withBaggageFrom(SpanContext from) {
         for (Entry<String, String> baggageItem : from.baggageItems()) {
             this.withBaggageItem(baggageItem.getKey(), baggageItem.getValue());