Automatically detect common attributes from the request (#146)

* RequestHandler now parses standard attributes from request.

StackdriverExporter now maps the standard attributes to expected Stackdriver formatted attributes.

* Make common attribute names constants

* Add test for Stackdriver attribute mapping

* Add http.route constant and fix documentation

* Mock stackdriver client for tests

* Fix documentation description

Author: chingor13

src/Trace/Exporter/StackdriverExporter.php

@@ -23,6 +23,7 @@
 use Google\Cloud\Trace\Span;
 use Google\Cloud\Trace\Trace;
 use OpenCensus\Trace\Tracer\TracerInterface;
+use OpenCensus\Trace\Span as OCSpan;
 
 /**
  * This implementation of the ExporterInterface use the BatchRunner to provide
@@ -70,30 +71,14 @@
  */
 class StackdriverExporter implements ExporterInterface
 {
-    const VERSION = '0.1.0';
-
-    // These are Stackdriver Trace's common attributes
-    const AGENT = 'g.co/agent';
-    const COMPONENT = '/component';
-    const ERROR_MESSAGE = '/error/message';
-    const ERROR_NAME = '/error/name';
-    const HTTP_CLIENT_CITY = '/http/client_city';
-    const HTTP_CLIENT_COUNTRY = '/http/client_country';
-    const HTTP_CLIENT_PROTOCOL = '/http/client_protocol';
-    const HTTP_CLIENT_REGION = '/http/client_region';
-    const HTTP_HOST = '/http/host';
-    const HTTP_METHOD = '/http/method';
-    const HTTP_REDIRECTED_URL = '/http/redirected_url';
-    const HTTP_STATUS_CODE = '/http/status_code';
-    const HTTP_URL = '/http/url';
-    const HTTP_USER_AGENT = '/http/user_agent';
-    const PID = '/pid';
-    const TID = '/tid';
-
-    const GAE_APPLICATION_ERROR = 'g.co/gae/application_error';
-    const GAE_APP_MODULE = 'g.co/gae/app/module';
-    const GAE_APP_MODULE_VERSION = 'g.co/gae/app/module_version';
-    const GAE_APP_VERSION = 'g.co/gae/app/version';
+    const ATTRIBUTE_MAP = [
+        OCSpan::ATTRIBUTE_HOST => '/http/host',
+        OCSpan::ATTRIBUTE_PORT => '/http/port',
+        OCSpan::ATTRIBUTE_METHOD => '/http/method',
+        OCSpan::ATTRIBUTE_PATH => '/http/url',
+        OCSpan::ATTRIBUTE_USER_AGENT => '/http/user_agent',
+        OCSpan::ATTRIBUTE_STATUS_CODE => '/http/status_code'
+    ];
 
     use BatchTrait;
 
@@ -155,7 +140,6 @@ public function __construct(array $options = [])
      */
     public function report(TracerInterface $tracer)
     {
-        $this->processSpans($tracer);
         $spans = $this->convertSpans($tracer);
 
         if (empty($spans)) {
@@ -182,40 +166,43 @@ public function report(TracerInterface $tracer)
     }
 
     /**
-     * Perform any pre-conversion modification to the spans
+     * Convert spans into Stackdriver's expected JSON output format.
+     *
+     * @access private
      *
      * @param TracerInterface $tracer
-     * @param array $headers [optional] Array of headers to read from instead of $_SERVER
+     * @return Span[] Representation of the collected trace spans ready for serialization
      */
-    public function processSpans(TracerInterface $tracer, $headers = null)
+    public function convertSpans(TracerInterface $tracer)
     {
-        // detect common attributes
-        $this->addCommonAttributes($tracer, $headers);
+        // transform OpenCensus Spans to Google\Cloud\Trace\Spans
+        return array_map([$this, 'mapSpan'], $tracer->spans());
     }
 
-    /**
-     * Convert spans into Zipkin's expected JSON output format.
-     *
-     * @param TracerInterface $tracer
-     * @param Trace $trace
-     * @return array Representation of the collected trace spans ready for serialization
-     */
-    public function convertSpans(TracerInterface $tracer)
+    private function mapSpan($span)
     {
-        $traceId = $tracer->spanContext()->traceId();
+        return new Span($span->traceId(), [
+            'name' => $span->name(),
+            'startTime' => $span->startTime(),
+            'endTime' => $span->endTime(),
+            'spanId' => $span->spanId(),
+            'parentSpanId' => $span->parentSpanId(),
+            'attributes' => $this->mapAttributes($span->attributes()),
+            'stackTrace' => $span->stackTrace()
+        ]);
+    }
 
-        // transform OpenCensus Spans to Google\Cloud\Trace\Spans
-        return array_map(function ($span) use ($traceId) {
-            return new Span($traceId, [
-                'name' => $span->name(),
-                'startTime' => $span->startTime(),
-                'endTime' => $span->endTime(),
-                'spanId' => $span->spanId(),
-                'parentSpanId' => $span->parentSpanId(),
-                'attributes' => $span->attributes(),
-                'stackTrace' => $span->stackTrace()
-            ]);
-        }, $tracer->spans());
+    private function mapAttributes(array $attributes)
+    {
+        $newAttributes = [];
+        foreach ($attributes as $key => $value) {
+            if (array_key_exists($key, self::ATTRIBUTE_MAP)) {
+                $newAttributes[self::ATTRIBUTE_MAP[$key]] = $value;
+            } else {
+                $newAttributes[$key] = $value;
+            }
+        }
+        return $newAttributes;
     }
 
     /**
@@ -232,54 +219,4 @@ protected function getCallback()
 
         return [self::$client, $this->batchMethod];
     }
-
-    private function addCommonAttributes(&$tracer, $headers = null)
-    {
-        $headers = $headers ?: $_SERVER;
-        $spans = $tracer->spans();
-        if (empty($spans)) {
-            return;
-        }
-        $rootSpan = $spans[0];
-
-        $attributeMap = [
-            self::HTTP_URL => ['REQUEST_URI'],
-            self::HTTP_METHOD => ['REQUEST_METHOD'],
-            self::HTTP_CLIENT_PROTOCOL => ['SERVER_PROTOCOL'],
-            self::HTTP_USER_AGENT => ['HTTP_USER_AGENT'],
-            self::HTTP_HOST => ['HTTP_HOST', 'SERVER_NAME'],
-            self::GAE_APP_MODULE => ['GAE_SERVICE'],
-            self::GAE_APP_MODULE_VERSION => ['GAE_VERSION'],
-            self::HTTP_CLIENT_CITY => ['HTTP_X_APPENGINE_CITY'],
-            self::HTTP_CLIENT_REGION => ['HTTP_X_APPENGINE_REGION'],
-            self::HTTP_CLIENT_COUNTRY => ['HTTP_X_APPENGINE_COUNTRY']
-        ];
-        foreach ($attributeMap as $attributeKey => $headerKeys) {
-            if ($val = $this->detectKey($headerKeys, $headers)) {
-                $tracer->addAttribute($attributeKey, $val, ['span' => $rootSpan]);
-            }
-        }
-
-        $responseCode = http_response_code();
-        if ($responseCode == 301 || $responseCode == 302) {
-            foreach (headers_list() as $header) {
-                if (substr($header, 0, 9) == 'Location:') {
-                    $this->rootSpan->addAttribute(self::HTTP_REDIRECTED_URL, substr($header, 10));
-                    break;
-                }
-            }
-        }
-        $tracer->addAttribute(self::PID, '' . getmypid(), ['span' => $rootSpan]);
-        $tracer->addAttribute(self::AGENT, 'opencensus-php [' . self::VERSION . ']', ['span' => $rootSpan]);
-    }
-
-    private function detectKey(array $keys, array $array)
-    {
-        foreach ($keys as $key) {
-            if (array_key_exists($key, $array)) {
-                return $array[$key];
-            }
-        }
-        return null;
-    }
 }

src/Trace/RequestHandler.php

@@ -36,6 +36,13 @@
 class RequestHandler
 {
     const DEFAULT_ROOT_SPAN_NAME = 'main';
+    const ATTRIBUTE_MAP = [
+        Span::ATTRIBUTE_HOST => ['HTTP_HOST', 'SERVER_NAME'],
+        Span::ATTRIBUTE_PORT => ['SERVER_PORT'],
+        Span::ATTRIBUTE_METHOD => ['REQUEST_METHOD'],
+        Span::ATTRIBUTE_PATH => ['REQUEST_URI'],
+        Span::ATTRIBUTE_USER_AGENT => ['HTTP_USER_AGENT']
+    ];
 
     /**
      * @var ExporterInterface The reported to use at the end of the request
@@ -57,6 +64,11 @@ class RequestHandler
      */
     private $scope;
 
+    /**
+     * @var array Replacement $_SERVER variables
+     */
+    private $headers;
+
     /**
      * Create a new RequestHandler.
      *
@@ -79,11 +91,11 @@ public function __construct(
         array $options = []
     ) {
         $this->reporter = $reporter;
-        $headers = array_key_exists('headers', $options)
+        $this->headers = array_key_exists('headers', $options)
             ? $options['headers']
             : $_SERVER;
 
-        $spanContext = $propagator->extract($headers);
+        $spanContext = $propagator->extract($this->headers);
 
         // If the context force disables tracing, don't consult the $sampler.
         if ($spanContext->enabled() !== false) {
@@ -101,8 +113,8 @@ public function __construct(
             : new NullTracer();
 
         $spanOptions = $options + [
-            'startTime' => $this->startTimeFromHeaders($headers),
-            'name' => $this->nameFromHeaders($headers),
+            'startTime' => $this->startTimeFromHeaders($this->headers),
+            'name' => $this->nameFromHeaders($this->headers),
             'attributes' => []
         ];
         $this->rootSpan = $this->tracer->startSpan($spanOptions);
@@ -120,8 +132,7 @@ public function __construct(
      */
     public function onExit()
     {
-        $responseCode = http_response_code();
-        $this->rootSpan->setStatus($responseCode, "HTTP status code: $responseCode");
+        $this->addCommonRequestAttributes($this->headers);
 
         $this->scope->close();
         $this->reporter->report($this->tracer);
@@ -192,6 +203,22 @@ public function addAttribute($attribute, $value, $options = [])
         $this->tracer->addAttribute($attribute, $value, $options);
     }
 
+    public function addCommonRequestAttributes(array $headers)
+    {
+        $responseCode = http_response_code();
+        $this->rootSpan->setStatus($responseCode, "HTTP status code: $responseCode");
+        $this->tracer->addAttribute(Span::ATTRIBUTE_STATUS_CODE, $responseCode, [
+            'spanId' => $this->rootSpan->spanId()
+        ]);
+        foreach (self::ATTRIBUTE_MAP as $attributeKey => $headerKeys) {
+            if ($val = $this->detectKey($headerKeys, $headers)) {
+                $this->tracer->addAttribute($attributeKey, $val, [
+                    'spanId' => $this->rootSpan->spanId()
+                ]);
+            }
+        }
+    }
+
     private function startTimeFromHeaders(array $headers)
     {
         if (array_key_exists('REQUEST_TIME_FLOAT', $headers)) {
@@ -210,4 +237,14 @@ private function nameFromHeaders(array $headers)
         }
         return self::DEFAULT_ROOT_SPAN_NAME;
     }
+
+    private function detectKey(array $keys, array $array)
+    {
+        foreach ($keys as $key) {
+            if (array_key_exists($key, $array)) {
+                return $array[$key];
+            }
+        }
+        return null;
+    }
 }

src/Trace/Span.php

@@ -28,6 +28,15 @@ class Span
 {
     use AttributeTrait;
 
+    // See https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/HTTP.md#attributes
+    const ATTRIBUTE_HOST = 'http.host';
+    const ATTRIBUTE_PORT = 'http.port';
+    const ATTRIBUTE_METHOD = 'http.method';
+    const ATTRIBUTE_PATH = 'http.path';
+    const ATTRIBUTE_ROUTE = 'http.route';
+    const ATTRIBUTE_USER_AGENT = 'http.user_agent';
+    const ATTRIBUTE_STATUS_CODE = 'http.status_code';
+
     /**
      * Unique identifier for a trace. All spans from the same Trace share the
      * same `traceId`. 16-byte value encoded as a hex string.
@@ -145,6 +154,7 @@ class Span
     public function __construct($options = [])
     {
         $options += [
+            'traceId' => null,
             'attributes' => [],
             'timeEvents' => [],
             'links' => [],
@@ -153,6 +163,8 @@ public function __construct($options = [])
             'sameProcessAsParentSpan' => null
         ];
 
+        $this->traceId = $options['traceId'];
+
         if (array_key_exists('startTime', $options)) {
             $this->setStartTime($options['startTime']);
         }
@@ -188,6 +200,16 @@ public function __construct($options = [])
         $this->sameProcessAsParentSpan = $options['sameProcessAsParentSpan'];
     }
 
+    /**
+     * Retrive the trace id for this span.
+     *
+     * @return string
+     */
+    public function traceId()
+    {
+        return $this->traceId;
+    }
+
     /**
      * Retrieve the start time for this span.
      *

src/Trace/Tracer/ContextTracer.php

@@ -80,6 +80,7 @@ public function inSpan(array $spanOptions, callable $callable, array $arguments
     public function startSpan(array $spanOptions = [])
     {
         $spanOptions += [
+            'traceId' => $this->spanContext()->traceId(),
             'parentSpanId' => $this->spanContext()->spanId(),
             'startTime' => microtime(true)
         ];