[#43] Adds in process context propagation.

README.md

@@ -26,134 +26,156 @@ composer require opentracing/opentracing
 ## Usage
 
 When consuming this library one really only need to worry about a couple of key
-abstractions: the `Tracer::startSpan` method, the `Span` interface, and binding
-a `Tracer` at bootstrap time. Here are code snippets demonstrating some important
-use cases:
+abstractions: the `Tracer::startActiveSpan` and `Tracer::startSpan` method,
+the `Span` interface, and binding a `Tracer` at bootstrap time. Here are code snippets
+demonstrating some important use cases:
 
 ### Singleton initialization
 
 The simplest starting point is to set the global tracer. As early as possible, do:
 
 ```php
-    use OpenTracing\GlobalTracer;
-    use AnOpenTracingImplementation\MyTracer;
-
-    GlobalTracer::set(new MyTracer());
+use OpenTracing\GlobalTracer;
+
+GlobalTracer::set(new MyTracerImplementation());
 ```
 
 ### Creating a Span given an existing Request
 
-To start a new `Span`, you can use the `StartSpanFromContext` method.
+To start a new `Span`, you can use the `startActiveSpan` method.
 
 ```php
-    use OpenTracing\Formats;
-    use OpenTracing\GlobalTracer;
+use OpenTracing\Formats;
+use OpenTracing\GlobalTracer;
 
-    ...
+...
 
-    $spanContext = GlobalTracer::get()->extract(
-        Formats\HTTP_HEADERS,
-        $request->getHeaders()
-    );
+$spanContext = GlobalTracer::get()->extract(
+    Formats\HTTP_HEADERS,
+    getallheaders()
+);
+
+function doSomething() {
+    ...
 
-    function doSomething(SpanContext $spanContext, ...) {
-        ...
-
-        $span = GlobalTracer::get()->startSpan('my_span', [
-        	'child_of' => $spanContext,
-        ]);
-
-        ...
-
-        $span->log([
-            'event' => 'soft error',
-            'type' => 'cache timeout',
-            'waiter.millis' => 1500,
-        ])
-
-        $span->finish();
-    }
+    $span = GlobalTracer::get()->startActiveSpan('my_span', ['child_of' => $spanContext]);
+
+    ...
+
+    $span->log([
+        'event' => 'soft error',
+        'type' => 'cache timeout',
+        'waiter.millis' => 1500,
+    ])
+
+    $span->finish();
+}
 ```
 
 ### Starting an empty trace by creating a "root span"
 
-It's always possible to create a "root" `Span` with no parent or other causal
-reference.
+It's always possible to create a "root" `Span` with no parent or other causal reference.
 
 ```php
-    $span = $tracer->startSpan('my_span');
-    ...
-    $span->finish();
+$span = $tracer->startActiveSpan('my_first_span');
+...
+$span->finish();
 ```
 
-### Creating a (child) Span given an existing (parent) Span
+#### Creating a child span assigning parent manually
 
 ```php
-    function xyz(Span $parentSpan, ...) {
-        ...
-        $span = GlobalTracer::get()->startSpan(
-        	'my_span',
-        	[
-        		'child_of' => $parentSpan,
-        	]
-        );
-
-        $span->finish();
-        ...
-    }
+$parent = GlobalTracer::get()->startSpan('parent');
+
+$child = GlobalTracer::get()->startSpan('child', [
+    'child_of' => $parent
+]);
+
+...
+
+$child->finish();
+
+...
+
+$parent->finish();
+```
+
+#### Creating a child span using automatic active span management
+
+Every new span will take the active span as parent and it will take its spot.
+
+```php
+$parent = GlobalTracer::get()->startActiveSpan('parent');        
+
+...
+
+/*
+ * Since the parent span has been created by using startActiveSpan we don't need
+ * to pass a reference for this child span
+ */
+$child = GlobalTracer::get()->startActiveSpan('my_second_span');
+
+... 
+
+$child->finish();
+
+...
+
+$parent->finish();
 ```
 
 ### Serializing to the wire
 
 ```php
-    use OpenTracing\GlobalTracer;
-    use OpenTracing\Formats;
-
-    ...
+use GuzzleHttp\Client;
+use OpenTracing\Formats;
+
+...
+
+$tracer = GlobalTracer::get(); 
+
+$spanContext = $tracer->extract(
+    Formats\HTTP_HEADERS,
+    getallheaders()
+);
+
+try {
+    $span = $tracer->startSpan('my_span', ['child_of' => $spanContext]);
+
+    $client = new Client;
 
-    $tracer = GlobalTracer::get(); 
+    $headers = [];
 
-    $spanContext = $tracer->extract(
+    $tracer->inject(
+        $span->getContext(),
         Formats\HTTP_HEADERS,
-        $request->getHeaders()
+        $headers
     );
 
-    try {
-        $span = $tracer->startSpan('my_span', ['child_of' => $spanContext]);
-
-        $client = new GuzzleHttp\Client;
-
-        $headers = [];
-
-        $tracer->inject(
-            $span->getContext(),
-            Formats\HTTP_HEADERS,
-            $headers
-        );
-
-        $request = new \GuzzleHttp\Psr7\Request('GET', 'http://myservice', $headers);
-        $client->send($request);
-        ...
-    } catch (\Exception $e) {
-        ...
-    }
-    ...        
+    $request = new \GuzzleHttp\Psr7\Request('GET', 'http://myservice', $headers);
+    $client->send($request);
+    ...
+
+} catch (\Exception $e) {
+    ...
+}
+...    
 ```
 
 ### Deserializing from the wire
 
-When using http header for context propagation you can use either the `Request` or the `$_SERVER` variable:
+When using http header for context propagation you can use either the `Request` or the `$_SERVER`
+variable:
 
 ```php
-    use OpenTracing\GlobalTracer;
-    use OpenTracing\Formats;
-
-    $request = Request::createFromGlobals();
-    $tracer = GlobalTracer::get();
-    $spanContext = $tracer->extract(Formats\HTTP_HEADERS, $request->getHeaders());
-    $tracer->startSpan('my_span', [
-        'child_of' => $spanContext,
-    ]); 
+use OpenTracing\GlobalTracer;
+use OpenTracing\Formats;
+
+$tracer = GlobalTracer::get();
+$spanContext = $tracer->extract(Formats\HTTP_HEADERS, getallheaders());
+$tracer->startSpan('my_span', [
+    'child_of' => $spanContext,
+]); 
 ```
 
 ### Flushing Spans
@@ -167,19 +189,18 @@ cause problems for Tracer implementations. This is why the PHP API contains a
 ```php
 use OpenTracing\GlobalTracer;
 
-// Do application work, buffer spans in memory
 $application->run();
 
-fastcgi_finish_request();
-
-$tracer = GlobalTracer::get();
-$tracer->flush(); // release buffer to backend
+register_shutdown_function(function() use ($tracer) {
+    /* Flush the tracer to the backend */
+    $tracer = GlobalTracer::get();
+    $tracer->flush();
+});
 ```
 
 This is optional, tracers can decide to immediately send finished spans to a
 backend. The flush call can be implemented as a NO-OP for these tracers.
 
-
 ### Using Span Options
 
 Passing options to the pass can be done using either an array or the
@@ -191,7 +212,7 @@ SpanOptions wrapper object. The following keys are valid:
 - `tags` is an array with string keys and scalar values that represent OpenTracing tags.
 
 ```php
-$span = $tracer->createSpan('my_span', [
+$span = $tracer->startActiveSpan('my_span', [
     'child_of' => $spanContext,
     'tags' => ['foo' => 'bar'],
     'start_time' => time(),
@@ -217,5 +238,5 @@ Tracers will throw an exception if the requested format is not handled by them.
 
 ## Coding Style
 
-Opentracing PHP follows the [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
+OpenTracing PHP follows the [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
 coding standard and the [PSR-4](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md) autoloading standard.

src/OpenTracing/GlobalTracer.php

@@ -7,14 +7,14 @@ final class GlobalTracer
     /**
      * @var Tracer
      */
-    private static $instance = null;
+    private static $instance;
 
     /**
      * GlobalTracer::set sets the [singleton] Tracer returned by get().
      * Those who use GlobalTracer (rather than directly manage a Tracer instance)
      * should call GlobalTracer::set as early as possible in bootstrap, prior to
      * start a new span. Prior to calling GlobalTracer::set, any Spans started
-     * via the `Tracer::startSpan` (etc) globals are noops.
+     * via the `Tracer::startActiveSpan` (etc) globals are noops.
      *
      * @param Tracer $tracer
      */
@@ -33,7 +33,7 @@ public static function set(Tracer $tracer)
     public static function get()
     {
         if (self::$instance === null) {
-            self::$instance = NoopTracer::create();
+            self::$instance = Tracer::create();
         }
 
         return self::$instance;

src/OpenTracing/NoopScopeManager.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace OpenTracing;
+
+final class NoopScopeManager implements ScopeManager
+{
+    public static function create()
+    {
+        return new self();
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function activate(Span $span, $finishSpanOnClose)
+    {
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getActiveSpan()
+    {
+        return NoopSpan::create();
+    }
+}

src/OpenTracing/NoopSpan.php

@@ -32,6 +32,9 @@ public function finish($finishTime = null, array $logRecords = [])
     {
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function overwriteOperationName($newOperationName)
     {
     }

src/OpenTracing/NoopTracer.php

@@ -4,6 +4,22 @@
 
 final class NoopTracer implements Tracer
 {
+    /**
+     * {@inheritdoc}
+     */
+    public function getActiveSpan()
+    {
+        return NoopSpan::create();
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getScopeManager()
+    {
+        return new NoopScopeManager();
+    }
+
     public static function create()
     {
         return new self();
@@ -14,6 +30,14 @@ public static function create()
      */
     public function startSpan($operationName, $options = [])
     {
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function startActiveSpan($operationName, $finishSpanOnClose = true, $options = [])
+    {
+
         return NoopSpan::create();
     }