Add detached spans API (#62)

* Add generic Context class

* Context can fetch single values

* ContextTracer now uses generic Context

* Scope/context should now play nicely with the extension

* Remove Context::setCurrent

* Add @internal annotation for Context::reset()

* Add ability to set multiple context values at once

* Remove default span name

* Add ScopeTest

* Delegate fetching of the current SpanContext to the tracer impl.

Each implementation handles SpanContext differently.

* php cs fixes

* Update README documentation

* Fix static function call in documentation

* Adding withSpan tests

* Extension can accept spanId as option when starting a span

* Remove unused 'use' statements

Author: chingor13

README.md

@@ -124,12 +124,16 @@ $pi = RequestTracer::inSpan(['name' => 'expensive-operation'], 'calculatePi', [1
 ### Explicit Span Management
 
 ```php
-RequestTracer::startSpan(['name' => 'expensive-operation']);
+// Creates a detached span
+$span = RequestTracer::startSpan(['name' => 'expensive-operation']);
+
+// Opens a scope that attaches the span to the current context
+$scope = RequestTracer::withSpan($span);
 try {
     $pi = calculatePi(1000);
 } finally {
-    // Make sure we close the span to avoid mismatched span boundaries
-    RequestTracer::endSpan();
+    // Closes the scope (ends the span)
+    $scope->close();
 }
 ```
 

ext/opencensus_trace_span.c

@@ -356,7 +356,9 @@ int opencensus_trace_span_apply_span_options(opencensus_trace_span_t *span, zval
             span->name = zend_string_copy(Z_STR_P(v));
         } else if (strcmp(ZSTR_VAL(k), "kind") == 0) {
             span->kind = Z_LVAL_P(v);
-        }
+        } else if (strcmp(ZSTR_VAL(k), "spanId") == 0) {
+			span->span_id = zend_string_copy(Z_STR_P(v));
+		}
     } ZEND_HASH_FOREACH_END();
     return SUCCESS;
 }

ext/tests/context_span_id.phpt

@@ -0,0 +1,26 @@
+--TEST--
+OpenCensus Trace: Trace Context from provided spanId
+--FILE--
+<?php
+
+opencensus_trace_set_context("traceid", '12345678');
+opencensus_trace_begin('foo', ['spanId' => 'abcd1234']);
+$context = opencensus_trace_context();
+opencensus_trace_finish();
+echo "Context trace id: " . $context->traceId() . PHP_EOL;
+echo "Context span id: " . $context->spanId() . PHP_EOL;
+
+$spans = opencensus_trace_list();
+if (count($spans) == 1) {
+    $span = $spans[0];
+    echo "Span id: " . $span->spanId() . PHP_EOL;
+    echo "Parent span id: " . $span->parentSpanId() . PHP_EOL;
+} else {
+    echo "Wrong number of spans. Expected 1, got " . count($spans) . PHP_EOL;
+}
+?>
+--EXPECT--
+Context trace id: traceid
+Context span id: abcd1234
+Span id: abcd1234
+Parent span id: 12345678

src/Core/Context.php

@@ -100,6 +100,16 @@ public function value($key, $default = null)
             : $default;
     }
 
+    /**
+     * Returns all the contained data.
+     *
+     * @return array
+     */
+    public function values()
+    {
+        return $this->values;
+    }
+
     /**
      * Attaches this context, thus entering a new scope within which this
      * context is current(). The previously current context is returned.
@@ -128,16 +138,6 @@ public function detach(Context $toAttach)
         self::$current = $toAttach;
     }
 
-    /**
-     * Returns all the contained data.
-     *
-     * @return array
-     */
-    public function values()
-    {
-        return $this->values;
-    }
-
     /**
      * Returns the context associated with the current scope, will never return
      * null.

src/Core/Scope.php

@@ -0,0 +1,64 @@
+<?php
+/**
+ * Copyright 2017 OpenCensus 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.
+ */
+
+namespace OpenCensus\Core;
+
+/**
+ * This class in an implementation of a generic scope that has something to
+ * execute when the scope finishes.
+ *
+ * Example:
+ * ```
+ * $scope = RequestTracer::withSpan($span);
+ * try {
+ *   return do_something();
+ * } finally {
+ *   $scope->close();
+ * }
+ * ```
+ */
+class Scope
+{
+    /**
+     * @var callable
+     */
+    private $callback;
+
+    /**
+     * @var array
+     */
+    private $args;
+
+    /**
+     * Creates a new Scope
+     *
+     * @param callable $callback
+     */
+    public function __construct(callable $callback, $args = [])
+    {
+        $this->callback = $callback;
+        $this->args = $args;
+    }
+
+    /**
+     * Close and clean up the scope. Runs the initial callback provided.
+     */
+    public function close()
+    {
+        call_user_func_array($this->callback, $this->args);
+    }
+}

src/Trace/Exporter/StackdriverExporter.php

@@ -22,7 +22,7 @@
 use Google\Cloud\Trace\TraceClient;
 use Google\Cloud\Trace\TraceSpan;
 use OpenCensus\Trace\Tracer\TracerInterface;
-use OpenCensus\Trace\Span as OpenCensusSpan;
+use OpenCensus\Trace\Span;
 
 /**
  * This implementation of the ExporterInterface use the BatchRunner to provide
@@ -166,7 +166,7 @@ public function report(TracerInterface $tracer)
 
         // build a Trace object and assign Spans
         $trace = self::$client->trace(
-            $tracer->context()->traceId()
+            $tracer->spanContext()->traceId()
         );
         $trace->setSpans($spans);
 
@@ -203,8 +203,8 @@ public function processSpans(TracerInterface $tracer, $headers = null)
     public function convertSpans(TracerInterface $tracer)
     {
         $spanKindMap = [
-            OpenCensusSpan::SPAN_KIND_CLIENT => TraceSpan::SPAN_KIND_RPC_CLIENT,
-            OpenCensusSpan::SPAN_KIND_SERVER => TraceSpan::SPAN_KIND_RPC_SERVER
+            Span::SPAN_KIND_CLIENT => TraceSpan::SPAN_KIND_RPC_CLIENT,
+            Span::SPAN_KIND_SERVER => TraceSpan::SPAN_KIND_RPC_SERVER
         ];
 
         // transform OpenCensus Spans to Google\Cloud\Spans

src/Trace/Exporter/ZipkinExporter.php

@@ -107,7 +107,7 @@ public function convertSpans(TracerInterface $tracer, $headers = null)
         $headers = $headers ?: $_SERVER;
         $spans = $tracer->spans();
         $rootSpan = $spans[0];
-        $traceId = $tracer->context()->traceId();
+        $traceId = $tracer->spanContext()->traceId();
 
         $kindMap = [
             Span::SPAN_KIND_CLIENT => 'CLIENT',

src/Trace/Integrations/Guzzle/EventSubscriber.php

@@ -17,6 +17,7 @@
 
 namespace OpenCensus\Trace\Integrations\Guzzle;
 
+use OpenCensus\Core\Scope;
 use OpenCensus\Trace\RequestTracer;
 use OpenCensus\Trace\Propagator\HttpHeaderPropagator;
 use OpenCensus\Trace\Propagator\PropagatorInterface;
@@ -46,6 +47,11 @@ class EventSubscriber implements SubscriberInterface
      */
     private $propagator;
 
+    /**
+     * @var Scope
+     */
+    private $scope;
+
     /**
      * Create a new Guzzle event listener that creates trace spans and propagates the current
      * trace context to the downstream request.
@@ -82,13 +88,14 @@ public function onBefore(BeforeEvent $event)
         if ($context = RequestTracer::context()) {
             $request->setHeader($this->propagator->key(), $this->propagator->formatter->serialize($context));
         }
-        RequestTracer::startSpan([
+        $span = RequestTracer::startSpan([
             'name' => 'GuzzleHttp::request',
             'labels' => [
                 'method' => $request->getMethod(),
                 'uri' => $request->getUrl()
             ]
         ]);
+        $this->scope = RequestTracer::withSpan($span);
     }
 
     /**
@@ -99,6 +106,6 @@ public function onBefore(BeforeEvent $event)
      */
     public function onEnd(EndEvent $event)
     {
-        RequestTracer::endSpan();
+        $this->scope->close();
     }
 }

src/Trace/RequestHandler.php

@@ -17,6 +17,8 @@
 
 namespace OpenCensus\Trace;
 
+use OpenCensus\Core\Context;
+use OpenCensus\Core\Scope;
 use OpenCensus\Trace\Exporter\ExporterInterface;
 use OpenCensus\Trace\Sampler\SamplerInterface;
 use OpenCensus\Trace\Span;
@@ -47,6 +49,11 @@ class RequestHandler
      */
     private $tracer;
 
+    /**
+     * @var Scope
+     */
+    private $scope;
+
     /**
      * Create a new RequestHandler.
      *
@@ -71,33 +78,34 @@ public function __construct(
             ? $options['headers']
             : $_SERVER;
 
-        $context = $propagator->extract($headers);
+        $spanContext = $propagator->extract($headers);
 
         // If the context force disables tracing, don't consult the $sampler.
-        if ($context->enabled() !== false) {
-            $context->setEnabled($context->enabled() || $sampler->shouldSample());
+        if ($spanContext->enabled() !== false) {
+            $spanContext->setEnabled($spanContext->enabled() || $sampler->shouldSample());
         }
 
         // If the request was provided with a trace context header, we need to send it back with the response
         // including whether the request was sampled or not.
-        if ($context->fromHeader()) {
+        if ($spanContext->fromHeader()) {
             if (!headers_sent()) {
-                foreach ($propagator->inject($context, $headers) as $header => $value) {
+                foreach ($propagator->inject($spanContext, $headers) as $header => $value) {
                     header("$header: $value");
                 }
             }
         }
 
-        $this->tracer = $context->enabled()
-            ? extension_loaded('opencensus') ? new ExtensionTracer($context) : new ContextTracer($context)
+        $this->tracer = $spanContext->enabled()
+            ? extension_loaded('opencensus') ? new ExtensionTracer($spanContext) : new ContextTracer($spanContext)
             : new NullTracer();
 
         $spanOptions = $options + [
             'startTime' => $this->startTimeFromHeaders($headers),
             'name' => $this->nameFromHeaders($headers),
             'labels' => []
         ];
-        $this->tracer->startSpan($spanOptions);
+        $span = $this->tracer->startSpan($spanOptions);
+        $this->scope = $this->tracer->withSpan($span);
 
         register_shutdown_function([$this, 'onExit']);
     }
@@ -109,10 +117,7 @@ public function __construct(
      */
     public function onExit()
     {
-        // close all open spans
-        do {
-            $span = $this->tracer->endSpan();
-        } while ($span);
+        $this->scope->close();
         $this->reporter->report($this->tracer);
     }
 
@@ -156,23 +161,15 @@ public function startSpan(array $spanOptions = [])
     }
 
     /**
-     * Explicitly finish the current context (Span).
-     *
-     * @return Span
-     */
-    public function endSpan()
-    {
-        return $this->tracer->endSpan();
-    }
-
-    /**
-     * Return the current context (Span)
+     * Attaches the provided span as the current span and returns a Scope
+     * object which must be closed.
      *
-     * @return SpanContext
+     * @param Span $span
+     * @return Scope
      */
-    public function context()
+    public function withSpan(Span $span)
     {
-        return $this->tracer->context();
+        return $this->tracer->withSpan($span);
     }
 
     private function startTimeFromHeaders(array $headers)