Port ActiveSpanSource implementation from opentracing-python.

README.md

@@ -79,29 +79,42 @@ Its always possible to create a "root" span with no parent or causal reference:
 
 use OpenTracing;
 
-$span = OpenTracing::startSpan("operation_name");
+$span = OpenTracing::startManualSpan("operation_name");
 $span->finish();
 
 $tracer = OpenTracing::getGlobalTracer();
-$span = $tracer->startSpan("operation_name");
+$span = $tracer->startManualSpan("operation_name");
 $span->finish();
 ```
 
-### Creating a (child) Span given an existing (parent) Span
+### Creating a child Span given an existing parent Span
 
 ```php
 <?php
 
 use OpenTracing;
 
-$parent = OpenTracing::startSpan('parent');
-$child = OpenTracing::startSpan('child', ['child_of' => $parent]);
+$parent = OpenTracing::startManualSpan('parent');
+$child = OpenTracing::startManualSpan('child', ['child_of' => $parent]);
 $child->finish();
 $parent->finish();
 
 $tracer = OpenTracing::getGlobalTracer();
-$parent = $tracer->startSpan('parent');
-$child = $tracer->startSpan('child', ['child_of' => $parent]);
+$parent = $tracer->startManualSpan('parent');
+$child = $tracer->startManualSpan('child', ['child_of' => $parent]);
+$child->finish();
+$parent->finish();
+```
+
+### Creating a child Span using automatic active span management
+
+```php
+<?php
+
+use OpenTracing;
+
+$parent = OpenTracing::startActiveSpan('parent');
+$child = OpenTracing::startActiveSpan('child');
 $child->finish();
 $parent->finish();
 ```
@@ -119,7 +132,7 @@ use OpenTracing;
 
 $headers = [];
 
-$span = OpenTracing::startSpan("my_span");
+$span = OpenTracing::startManualSpan("my_span");
 OpenTracing::inject($span->getContext(), OpenTracing::FORMAT_HTTP_HEADERS, $headers);
 
 $ch = curl_init("http://opentracing.io");
@@ -144,7 +157,7 @@ use OpenTracing;
 
 $context = OpenTracing::extract(OpenTracing::FORMAT_SERVER_GLOBALS, $_SERVER);
 
-$span = OpenTracing::startSpan("my_span", ["child_of" => $context]);
+$span = OpenTracing::startManualSpan("my_span", ["child_of" => $context]);
 ```
 
 ### Working with multiple References
@@ -159,10 +172,10 @@ specify the relationships:
 use OpenTracing;
 use OpenTracing\Reference;
 
-$parent1 = OpenTracing::startSpan('parent');
-$parent2 = OpenTracing::startSpan('parent');
+$parent1 = OpenTracing::startManualSpan('parent');
+$parent2 = OpenTracing::startManualSpan('parent');
 
-$child = \OpenTracing::startSpan('child', [Reference::followsFrom($parent1), Reference::followsFrom($parent2)]);
+$child = \OpenTracing::startManualSpan('child', [Reference::followsFrom($parent1), Reference::followsFrom($parent2)]);
 $child->finish();
 $parent->finish();
 ```
@@ -185,7 +198,7 @@ technically only the Tracer implementation needs them to validate the inputs.
 
 use OpenTracing\SpanOptions;
 
-$span = $tracer->createSpan('operation', new SpanOptions([
+$span = $tracer->startManualSpan('operation', new SpanOptions([
     'child_of' => $parentContext,
     'tags' => ['foo' => 'bar'],
     'start_time' => $microtime,

src/OpenTracing.php

@@ -35,9 +35,19 @@ private static function getGlobalTracer()
      * @param array|SpanOptions $options
      * @return \OpenTracing\Span
      */
-    public static function startSpan($operationName, array $options = array())
+    public static function startActiveSpan($operationName, array $options = array())
     {
-        return self::getGlobalTracer()->startSpan($operationName, $options);
+        return self::getGlobalTracer()->startActiveSpan($operationName, $options);
+    }
+
+    /**
+     * @param string $operationName
+     * @param array|SpanOptions $options
+     * @return \OpenTracing\Span
+     */
+    public static function startManualSpan($operationName, array $options = array())
+    {
+        return self::getGlobalTracer()->startManualSpan($operationName, $options);
     }
 
     /**

src/OpenTracing/ActiveSpanSource.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace OpenTracing;
+
+/**
+ * `ActiveSpanSource` is the interface for a pluggable class that
+ * keeps track of the current active `Span`.
+ */
+interface ActiveSpanSource
+{
+    /**
+     * Sets the given `Span` as active, 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.
+     */
+    public function makeActive(Span $span);
+
+    /**
+     * Returns the `Span` that is currently activated for this source.
+     *
+     * @return \OpenTracing\Span
+     */
+    public function getActiveSpan();
+
+    /**
+     * 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.
+     */
+    public function deactivate(Span $span);
+}

src/OpenTracing/NullActiveSpanSource.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace OpenTracing;
+
+class NullActiveSpanSource implements ActiveSpanSource
+{
+    private $activeSpan;
+
+    public function __construct()
+    {
+        $this->activeSpan = new NullSpan();
+    }
+
+    /**
+     * Sets the given `Span` as active, 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.
+     */
+    public function makeActive(Span $span)
+    {
+    }
+
+    /**
+     * Returns the `Span` that is currently activated for this source.
+     *
+     * @return \OpenTracing\Span
+     */
+    public function getActiveSpan()
+    {
+        return $this->activeSpan;
+    }
+
+    /**
+     * 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.
+     */
+    public function deactivate(Span $span)
+    {
+    }
+}

src/OpenTracing/NullSpan.php

@@ -4,9 +4,16 @@
 
 class NullSpan implements Span
 {
+    private $context;
+
+    public function __construct()
+    {
+        $this->context = new NullSpanContext();
+    }
+
     public function getContext()
     {
-        return NullSpanContext();
+        return $this->context;
     }
 
     public function setTag($name, $value)

src/OpenTracing/NullTracer.php

@@ -4,9 +4,33 @@
 
 class NullTracer implements Tracer
 {
-    public function startSpan($operationName, array $options)
+    private $activeSpanSource;
+    private $nullSpan;
+
+    public function __construct()
+    {
+        $this->activeSpanSource = new NullActiveSpanSource();
+        $this->nullSpan = new NullSpan();
+    }
+
+    public function getActiveSpanSource()
+    {
+        return $this->activeSpanSource;
+    }
+
+    public function getActiveSpan()
+    {
+        return $this->activeSpanSource->getActiveSpan();
+    }
+
+    public function startActiveSpan($operationName, $options = array())
+    {
+        return $this->nullSpan;
+    }
+
+    public function startManualSpan($operationName, $options = array())
     {
-        return new NullSpan();
+        return $this->nullSpan;
     }
 
     public function inject(SpanContext $context, $format, &$carrier)
@@ -15,6 +39,10 @@ public function inject(SpanContext $context, $format, &$carrier)
 
     public function extract($format, $carrier)
     {
-        return new NullSpanContext();
+        return $this->nullSpan->getContext();
+    }
+
+    public function flush()
+    {
     }
 }

src/OpenTracing/Tracer.php

@@ -5,11 +5,52 @@
 interface Tracer
 {
     /**
+     * @return \OpenTracing\ActiveSpanSource
+     */
+    public function getActiveSpanSource();
+
+    /**
+     * @return \OpenTracing\Span
+     */
+    public function getActiveSpan();
+
+    /**
+     * 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 array|SpanOptions $options
+     * @return \OpenTracing\Span
+     */
+    public function startActiveSpan($operationName, $options = array());
+
+    /**
+     * Starts and returns a new Span representing a unit of work.
+     *
      * @param string $operationName
      * @param array|SpanOptions $options
      * @return \OpenTracing\Span
      */
-    public function startSpan($operationName, $options = array());
+    public function startManualSpan($operationName, $options = array());
 
     /**
      * @param string $format

tests/OpenTracingTest.php

@@ -2,15 +2,27 @@
 
 class OpenTracingTest extends \PHPUnit_Framework_TestCase
 {
-    public function testStartSpanFromGlobalTracer()
+    public function testStartManualSpanFromGlobalTracer()
     {
         $tracer = $this->getMockBuilder('OpenTracing\Tracer')->getMock();
-        $tracer->method('startSpan')->willReturn($this->getMockBuilder('OpenTracing\Span')->getMock());
+        $tracer->method('startManualSpan')->willReturn($this->getMockBuilder('OpenTracing\Span')->getMock());
 
         \OpenTracing::setGlobalTracer($tracer);
 
-        $span = \OpenTracing::startSpan('php');
+        $span = \OpenTracing::startManualSpan('php');
 
         $this->assertInstanceOf('OpenTracing\Span', $span);
     }
+
+    public function testStartNullTracer()
+    {
+        $tracer = new \OpenTracing\NullTracer();
+
+        $this->assertInstanceOf(\OpenTracing\ActiveSpanSource::class, $tracer->getActiveSpanSource());
+        $this->assertInstanceOf(\OpenTracing\Span::class, $tracer->startManualSpan("foo"));
+        $this->assertInstanceOf(\OpenTracing\Span::class, $tracer->startActiveSpan("foo"));
+        $this->assertInstanceOf(\OpenTracing\Span::class, $tracer->getActiveSpan());
+        $this->assertInstanceOf(\OpenTracing\SpanContext::class, $tracer->getActiveSpan()->getContext());
+        $this->assertInstanceOf(\OpenTracing\SpanContext::class, $tracer->extract(\OpenTracing::FORMAT_TEXT_MAP, []));
+    }
 }