Adds activeSpanSource interface and include it as a dependency on tra…

…cer.

src/OpenTracing/ActiveSpanSource.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace OpenTracing;
+
+/**
+ * Keeps track of the current active `Span`.
+ */
+interface ActiveSpanSource
+{
+    const THREAD_DEFAULT = 'default';
+
+    /**
+     * Activates an `Span`, so that it is used as a parent when creating new spans.
+     * The implementation must keep track of the active spans sequence, so
+     * that previous spans can be resumed after a deactivation.
+     *
+     * @param Span $span
+     * @param string|array $threads Use only in case of async operations. Allows you to keep
+     * an span as active in different threads.
+     */
+    public function activate(Span $span, $threads = self::THREAD_DEFAULT);
+
+    /**
+     * Returns current active `Span` for a given thread.
+     *
+     * @param string $thread
+     * @return Span
+     */
+    public function activeSpan($thread = self::THREAD_DEFAULT);
+
+    /**
+     * Deactivate the given `Span`, restoring the previous active one.
+     *
+     * This method must take in consideration that a `Span` may be deactivated
+     * when it's not really active. In that case, the current active stack
+     * must not be changed (idempotency).
+     *
+     * Do not confuse it with the finish concept:
+     *  - $span->deactivate() -> the span is not active but still "running"
+     *  - $span->finish() -> the span is finished and deactivated
+     *
+     * @param Span $span
+     */
+    public function deactivate(Span $span);
+}

src/OpenTracing/NoopActiveSpanSource.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace OpenTracing;
+
+final class NoopActiveSpanSource implements ActiveSpanSource
+{
+    public static function create()
+    {
+        return new self();
+    }
+
+    public function activate(Span $span, $threads = self::THREAD_DEFAULT)
+    {
+    }
+
+    public function activeSpan($thread = self::THREAD_DEFAULT)
+    {
+        return NoopSpan::create();
+    }
+
+    public function deactivate(Span $span)
+    {
+    }
+}

src/OpenTracing/NoopSpan.php

@@ -9,40 +9,67 @@ public static function create()
         return new self();
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function operationName()
     {
         return 'noop_span';
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function context()
     {
         return null;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function finish($finishTime = null, $logRecords = [])
     {
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function overwriteOperationName($newOperationName)
     {
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setTag($tag)
     {
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function logFields(array $logs)
     {
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function log(array $logs)
     {
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setBaggageItem($key, $value)
     {
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function baggageItem($key)
     {
         return null;

src/OpenTracing/NoopTracer.php

@@ -4,7 +4,6 @@
 
 use OpenTracing\Propagators\Reader;
 use OpenTracing\Propagators\Writer;
-use TracingContext\TracingContext;
 
 final class NoopTracer implements Tracer
 {
@@ -13,16 +12,29 @@ public static function create()
         return new self();
     }
 
-    public function startSpan(
+    /**
+     * {@inheritdoc}
+     */
+    public function startActiveSpan(
         $operationName,
         SpanReference $parentReference = null,
         $startTimestamp = null,
         array $tags = []
     ) {
+
         return NoopSpan::create();
     }
 
-    public function startSpanWithOptions($operationName, $options)
+    public function startManualSpan(
+        $operationName,
+        SpanReference $parentReference = null,
+        $startTimestamp = null,
+        array $tags = []
+    ) {
+        return NoopSpan::create();
+    }
+
+    public function startSpanWithOptions($operationName, $options = [])
     {
         return NoopSpan::create();
     }
@@ -39,4 +51,14 @@ public function extract($format, Reader $carrier)
     public function flush()
     {
     }
+
+    public function activeSpanSource()
+    {
+        return NoopActiveSpanSource::create();
+    }
+
+    public function activeSpan($thread = ActiveSpanSource::THREAD_DEFAULT)
+    {
+        return NoopSpan::create();
+    }
 }

src/OpenTracing/Span.php

@@ -18,7 +18,6 @@ public function context();
      * @param float|int|\DateTimeInterface|null $finishTime if passing float or int
      * it should represent the timestamp (including as many decimal places as you need)
      * @param array $logRecords
-     * @return mixed
      */
     public function finish($finishTime = null, $logRecords = []);
 

src/OpenTracing/SpanOptions.php

@@ -22,6 +22,11 @@ final class SpanOptions
      */
     private $startTime;
 
+    /**
+     * @var bool
+     */
+    private $isActive = true;
+
     private function __construct()
     {
         new self();
@@ -33,6 +38,10 @@ public static function create(array $options)
 
         foreach ($options as $key => $value) {
             switch ($key) {
+                case 'is_active':
+                    $spanOptions->isActive = (bool) $value;
+                    break;
+
                 case 'child_of':
                     $spanOptions->childOf = self::buildChildOf($value);
                     break;

src/OpenTracing/Tracer.php

@@ -2,20 +2,73 @@
 
 namespace OpenTracing;
 
+use OpenTracing\Carriers\HttpHeaders;
+use OpenTracing\Carriers\TextMap;
 use OpenTracing\Propagators\Reader;
 use OpenTracing\Propagators\Writer;
 
 interface Tracer
 {
+    const FORMAT_BINARY = 1;
+
     /**
+     * @see HttpHeaders
+     */
+    const FORMAT_TEXT_MAP = 2;
+
+    /**
+     * @see TextMap
+     */
+    const FORMAT_HTTP_HEADERS = 3;
+
+    /**
+     * Starts and returns a new `Span` representing a unit of work.
+     *
+     * This method differs from `startManualSpan` because it uses in-process
+     * context propagation to keep track of the current active `Span` (if
+     * available).
+     *
+     * Starting a root `Span` with no casual references and a child `Span`
+     * in a different function, is possible without passing the parent
+     * reference around:
+     *
+     *     function handleRequest($request)
+     *     {
+     *         $rootSpan = $this->tracer->startActiveSpan('request.handler');
+     *         $data = $this->getData($request);
+     *     }
+     *
+     *     function getData($request)
+     *     {
+     *         // `$chilSpan` has `$rootSpan` as parent.
+     *         $childSpan = $this->tracer->startActiveSpan('db.query');
+     *     }
+     *
      * @param string $operationName
      * @param SpanReference|null $parentReference
      * @param float|int|\DateTimeInterface|null $startTimestamp if passing float or int
      * it should represent the timestamp (including as many decimal places as you need)
      * @param Tag[] $tags
      * @return Span
      */
-    public function startSpan(
+    public function startActiveSpan(
+        $operationName,
+        SpanReference $parentReference = null,
+        $startTimestamp = null,
+        array $tags = []
+    );
+
+    /**
+     * Starts and returns a new Span representing a unit of work.
+     *
+     * @param string $operationName
+     * @param SpanReference|null $parentReference
+     * @param float|int|\DateTimeInterface|null $startTimestamp if passing float or int
+     * it should represent the timestamp (including as many decimal places as you need)
+     * @param Tag[] $tags
+     * @return Span
+     */
+    public function startManualSpan(
         $operationName,
         SpanReference $parentReference = null,
         $startTimestamp = null,
@@ -27,17 +80,28 @@ public function startSpan(
      * @param array|SpanOptions $options
      * @return Span
      */
-    public function startSpanWithOptions($operationName, $options);
+    public function startSpanWithOptions($operationName, $options = []);
+
+    /**
+     * @return ActiveSpanSource
+     */
+    public function activeSpanSource();
+
+    /**
+     * @param string|array $thread
+     * @return Span
+     */
+    public function activeSpan($thread = ActiveSpanSource::THREAD_DEFAULT);
 
     /**
      * @param SpanContext $spanContext
-     * @param string $format
+     * @param int $format
      * @param Writer $carrier
      */
     public function inject(SpanContext $spanContext, $format, Writer $carrier);
 
     /**
-     * @param string $format
+     * @param int $format
      * @param Reader $carrier
      * @return SpanContext
      */
@@ -48,9 +112,12 @@ public function extract($format, Reader $carrier);
      *
      * This method might not be needed depending on the tracing implementation
      * but one should make sure this method is called after the request is finished.
-     * As an implementor, a good idea would be to use an asynchronous {@ see message bus}
-     * or use the call to {@see fastcgi_finish_request} in order to not to delay the end
-     * of the request to the final user.
+     * As an implementor, a good idea would be to use an asynchronous message bus
+     * or use the call to fastcgi_finish_request in order to not to delay the end
+     * of the request to the client.
+     *
+     * @see fastcgi_finish_request()
+     * @see https://www.google.com/search?q=message+bus+php
      */
     public function flush();
 }