Trace: Guzzle Integration #25

Author: iamacarpet

composer.json

@@ -10,7 +10,8 @@
     ],
     "require": {
         "opencensus/opencensus-exporter-stackdriver": "^0.1.0",
-        "google/cloud-logging": "^1.12"
+        "google/cloud-logging": "^1.12",
+        "guzzlehttp/guzzle": "~6"
     },
     "require-dev": {
     },

docs/trace.md

@@ -23,7 +23,7 @@ By default, this includes:
   * PDO
   * Eloquent (Laravel)
   * (soon) Datastore
-  * (soon) Guzzle (HTTP(s))
+  * Guzzle (HTTP(s))
 
 It also allows you to register your own trace providers to be registered as the application boots, via the config file for this package (`trace_providers` in `gaesupport.php`).
 
@@ -122,4 +122,9 @@ Next, update your `gaesupport.php` configuration file to include that trace prov
 ## Installation
 Since the low level trace setup is done as part of the composer autoloader initialisation, most of the installation is taken care of once you've installed the package, although for the higher level & custom trace providers, you'll need to make sure the `GaeSupportServiceProvider` and `TraceServiceProvider` are both loaded into Laravel.
 
-In Laravel 5.5, service providers are automatically discovered by default, so unless you've disabled this functionality, you shouldn't need to do anything else either.
+In Laravel 5.5, service providers are automatically discovered by default, so unless you've disabled this functionality, you shouldn't need to do anything else either.
+
+## Guzzle Sub-Request Trace Merging
+StackDriver Trace has the ability to show trace points from sub-requests within the same project (although it can be to other App Engine services) into the same trace entry in the GUI, allowing you to view the aggregate impact of a whole request in a micro-service environment.
+
+To take advantage of this, replace your `GuzzleHttp\Client` with `A1comms\GaeSupportLaravel\Integration\Guzzle\Client`.

src/A1comms/GaeSupportLaravel/Integration/Guzzle/Client.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace A1comms\GaeSupportLaravel\Integration\Guzzle;
+
+use GuzzleHttp\Client as GuzzleClient;
+use A1comms\GaeSupportLaravel\Trace\Integration\Guzzle\Middleware as TraceMiddleware;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Extension to Guzzle Client to apply relevant middleware & config.
+ */
+class Client extends GuzzleClient
+{
+    /**
+     * e.g.
+     *      $client = new Client([
+     *          ...standard guzzle config...,
+     *          'gaesupport' => [
+     *              'trace' => false,
+     *              'auth'  => [
+     *                  ...auth config placeholder...,
+     *              ],
+     *          ],
+     *      ]);
+     */
+    public function __construct(array $config = [])
+    {
+        if ((!is_gae()) || (php_sapi_name() == 'cli')) {
+            return parent::__construct($config);
+        }
+
+        if (!isset($config['handler']))
+        {
+            $config['handler'] = HandlerStack::create();
+            $config['handler']->setHandler(\GuzzleHttp\choose_handler());
+        }
+
+        if (method_exists($config['handler'], 'push'))
+        {
+            // We are able to modify the handler stack, continue...
+
+            // Unless disabled, add TraceMiddleware for sub-request trace merging in StackDriver.
+            if (@$config['gaesupport']['trace'] !== false)
+            {
+                $config['handler']->push(new TraceMiddleware());
+            }
+        }
+        else
+        {
+            Log::warning('A1comms\\GaeSupportLaravel\\Integration\\Guzzle\\Client: Unable to modify handler stack, no push method defined');
+        }
+
+        return parent::__construct($config);
+    }
+}

src/A1comms/GaeSupportLaravel/Trace/Integration/Guzzle/Middleware.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace A1comms\GaeSupportLaravel\Trace\Integration\Guzzle;
+
+use OpenCensus\Trace\Tracer;
+use OpenCensus\Trace\Propagator\HttpHeaderPropagator;
+use OpenCensus\Trace\Propagator\PropagatorInterface;
+use Psr\Http\Message\RequestInterface;
+
+class Middleware
+{
+    /**
+     * @var PropagatorInterface
+     */
+    private $propagator;
+
+    /**
+     * Create a new Guzzle middleware that creates trace spans and propagates the current
+     * trace context to the downstream request.
+     *
+     * @param PropagatorInterface $propagator Interface responsible for serializing trace context
+     */
+    public function __construct(PropagatorInterface $propagator = null)
+    {
+        $this->propagator = $propagator ?: new HttpHeaderPropagator();
+    }
+
+    /**
+     * Magic method which makes this object callable. Guzzle middleware are expected to be
+     * callables.
+     *
+     * @param  callable $handler The next handler in the HandlerStack
+     * @return callable
+     */
+    public function __invoke(callable $handler)
+    {
+        return function (RequestInterface $request, $options) use ($handler) {
+            $context = Tracer::spanContext();
+            if ($context->enabled()) {
+                $request = $request->withHeader(
+                    $this->propagator->key(),
+                    $this->propagator->formatter()->serialize($context)
+                );
+            }
+            return $handler($request, $options);
+        };
+    }
+}

src/A1comms/GaeSupportLaravel/Trace/Integration/Guzzle/TraceProvider.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace A1comms\GaeSupportLaravel\Trace\Integration\Guzzle;
+
+use OpenCensus\Trace\Integrations\IntegrationInterface;
+use GuzzleHttp\Client as GuzzleClient;
+
+class TraceProvider implements IntegrationInterface
+{
+    public static function load()
+    {
+        if (!extension_loaded('opencensus')) {
+            trigger_error('opencensus extension required to load Laravel integrations.', E_USER_WARNING);
+            return;
+        }
+
+        opencensus_trace_method(GuzzleClient::class, '__call', [self::class, 'handleRequest']);
+    }
+
+    public static function handleRequest($scope, $method, $args)
+    {
+        return [
+            'name' => 'GuzzleHttp::request',
+            'attributes' => [
+                'method' => $method,
+                'uri' => (count($args) < 1) ? 'invalid' : $args[0],
+            ],
+        ];
+    }
+}

src/A1comms/GaeSupportLaravel/Trace/LowLevelLoader.php

@@ -23,6 +23,7 @@ public static function getList()
             OpenCensus\Trace\Integrations\Mysql::class,
             OpenCensus\Trace\Integrations\PDO::class,
             OpenCensus\Trace\Integrations\Memcached::class,
+            A1comms\GaeSupportLaravel\Trace\Integration\Guzzle\TraceProvider::class,
         ];
     }
 }