Binary propagation (#30)

* Add test for binary propagation

* Implement the binary propagator

* Fix Guzzle integrations to accept a propagator interface

* Fix binary propagator to use the OPTION_ENABLED constant instead of a hard coded int

* Split PropagatorInterface with FormatterInterface

* Fix grpc and Guzzle integrations to use the new PropagatorInterface

* Fix alias for the Guzzle integrations

* Update docs

* Fix CS

* Add example for propagating TraceContext over Grpc

* Add tests for PropagatorInterface inject

* Fix grammar in docs

* Add test for when an invalid format is attempted deserialization

* Catch a bad binary format, trigger a warning and return an empty TraceContext

Author: chingor13

src/Trace/Integrations/Grpc.php

@@ -18,6 +18,8 @@
 namespace OpenCensus\Trace\Integrations;
 
 use Grpc\BaseStub;
+use OpenCensus\Trace\RequestTracer;
+use OpenCensus\Trace\Propagator\GrpcMetadataPropagator;
 
 /**
  * This class handles instrumenting grpc requests using the opencensus extension.
@@ -88,4 +90,35 @@ public static function load()
             ];
         });
     }
+
+    /**
+     * Update metadata handler for grpc clients.
+     *
+     * Example:
+     *
+     * ```
+     * use OpenCensus\Trace\Integrations\Grpc;
+     *
+     * # MathClient is the generated client from the proto definition
+     * $client = new Math\MathClient($host, ['update_metadata' => [Grpc::class, 'updateMetadata']]);
+     *
+     * # The call will pass the current trace context using the GrpcMetadataPropagator and BinaryFormatter
+     * $call = $client->Div($divArgs);
+     * $response = $call->wait();
+     * ```
+     *
+     * @param array $metadata
+     * @param string $jwtAuthUri
+     * @return array
+     */
+    public static function updateMetadata($metadata, $jwtAuthUri)
+    {
+        if ($context = RequestTracer::context()) {
+            $propagator = new GrpcMetadataPropagator();
+            $metadata += [
+                $propagator->key() => $propagator->formatter()->serialize($context)
+            ];
+        }
+        return $metadata;
+    }
 }

src/Trace/Integrations/Guzzle/EventSubscriber.php

@@ -18,6 +18,8 @@
 namespace OpenCensus\Trace\Integrations\Guzzle;
 
 use OpenCensus\Trace\RequestTracer;
+use OpenCensus\Trace\Propagator\HttpHeaderPropagator;
+use OpenCensus\Trace\Propagator\PropagatorInterface;
 use GuzzleHttp\Event\BeforeEvent;
 use GuzzleHttp\Event\EndEvent;
 use GuzzleHttp\Event\SubscriberInterface;
@@ -39,7 +41,21 @@
  */
 class EventSubscriber implements SubscriberInterface
 {
-    const TRACE_CONTEXT_HEADER = 'X-Cloud-Trace-Context';
+    /**
+     * @var PropagatorInterface
+     */
+    private $propagator;
+
+    /**
+     * Create a new Guzzle event listener 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();
+    }
 
     /**
      * Returns an array of event names this subscriber wants to listen to.
@@ -64,7 +80,7 @@ public function onBefore(BeforeEvent $event)
     {
         $request = $event->getRequest();
         if ($context = RequestTracer::context()) {
-            $request->setHeader(self::TRACE_CONTEXT_HEADER, $context);
+            $request->setHeader($this->propagator->key(), $this->propagator->formatter->serialize($context));
         }
         RequestTracer::startSpan([
             'name' => 'GuzzleHttp::request',

src/Trace/Integrations/Guzzle/Middleware.php

@@ -18,6 +18,8 @@
 namespace OpenCensus\Trace\Integrations\Guzzle;
 
 use OpenCensus\Trace\RequestTracer;
+use OpenCensus\Trace\Propagator\HttpHeaderPropagator;
+use OpenCensus\Trace\Propagator\PropagatorInterface;
 use Psr\Http\Message\RequestInterface;
 
 /**
@@ -39,7 +41,23 @@
  */
 class Middleware
 {
-    const TRACE_CONTEXT_HEADER = 'X-Cloud-Trace-Context';
+    const DEFAULT_HEADER_NAME = 'X-Cloud-Trace-Context';
+
+    /**
+     * @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
@@ -52,7 +70,10 @@ public function __invoke(callable $handler)
     {
         return function (RequestInterface $request, $options) use ($handler) {
             if ($context = RequestTracer::context()) {
-                $request = $request->withHeader(self::TRACE_CONTEXT_HEADER, $context);
+                $request = $request->withHeader(
+                    $this->propagator->key(),
+                    $this->propagator->formatter()->serialize($context)
+                );
             }
             return RequestTracer::inSpan([
                 'name' => 'GuzzleHttp::request',

src/Trace/Propagator/BinaryFormatter.php

@@ -0,0 +1,62 @@
+<?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\Trace\Propagator;
+
+use OpenCensus\Trace\TraceContext;
+
+/**
+ * This propagator contains the method for serializaing and deserializing
+ * TraceContext over a binary format.
+ *
+ * See https://github.com/census-instrumentation/opencensus-specs/blob/master/encodings/BinaryEncoding.md
+ * for the encoding specification.
+ */
+class BinaryFormatter implements FormatterInterface
+{
+    const OPTION_ENABLED = 1;
+
+    /**
+     * Generate a TraceContext object from the Trace Context header
+     *
+     * @param string $header
+     * @return TraceContext
+     */
+    public function deserialize($bin)
+    {
+        $data = @unpack('Cversion/Cfield0/H32traceId/Cfield1/H16spanId/Cfield2/Coptions', $bin);
+        if ($data === false) {
+            trigger_error('Invalid binary format for TraceContext', E_USER_WARNING);
+            return new TraceContext();
+        }
+        $enabled = !!($data['options'] & self::OPTION_ENABLED);
+        return new TraceContext($data['traceId'], hexdec($data['spanId']), $enabled, true);
+    }
+
+    /**
+     * Convert a TraceContext to header string
+     *
+     * @param TraceContext $context
+     * @return string
+     */
+    public function serialize(TraceContext $context)
+    {
+        $spanHex = str_pad(dechex($context->spanId()), 16, "0", STR_PAD_LEFT);
+        $traceOptions = $context->enabled() ? self::OPTION_ENABLED : 0;
+        return pack("CCH*CH*CC", 0, 0, $context->traceId(), 1, $spanHex, 2, $traceOptions);
+    }
+}

src/Trace/Propagator/CloudTraceFormatter.php

@@ -0,0 +1,67 @@
+<?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\Trace\Propagator;
+
+use OpenCensus\Trace\TraceContext;
+
+/**
+ * This format using a human readable string encoding to propagate TraceContext.
+ * The current format of the header is <trace-id>[/<span-id>][;o=<options>].
+ * The options are a bitmask of options. Currently the only option is the
+ * least significant bit which signals whether the request was traced or not
+ * (1 = traced, 0 = not traced).
+ */
+class CloudTraceFormatter implements FormatterInterface
+{
+    const CONTEXT_HEADER_FORMAT = '/([0-9a-f]{32})(?:\/(\d+))?(?:;o=(\d+))?/';
+
+    /**
+     * Generate a TraceContext object from the Trace Context header
+     *
+     * @param string $header
+     * @return TraceContext
+     */
+    public function deserialize($header)
+    {
+        if (preg_match(self::CONTEXT_HEADER_FORMAT, $header, $matches)) {
+            return new TraceContext(
+                $matches[1],
+                array_key_exists(2, $matches) ? $matches[2] : null,
+                array_key_exists(3, $matches) ? $matches[3] == '1' : null,
+                true
+            );
+        }
+        return new TraceContext();
+    }
+
+    /**
+     * Convert a TraceContext to header string
+     *
+     * @param TraceContext $context
+     * @return string
+     */
+    public function serialize(TraceContext $context)
+    {
+        $ret = '' . $context->traceId();
+        if ($context->spanId()) {
+            $ret .= '/' . $context->spanId();
+        }
+        $ret .= ';o=' . ($context->enabled() ? '1' : '0');
+        return $ret;
+    }
+}

src/Trace/Propagator/FormatterInterface.php

@@ -0,0 +1,42 @@
+<?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\Trace\Propagator;
+
+use OpenCensus\Trace\TraceContext;
+
+/**
+ * This interface lets us define serialization strategies for TraceContext.
+ */
+interface FormatterInterface
+{
+    /**
+     * Generate a TraceContext object from the Trace Context header
+     *
+     * @param string $header
+     * @return TraceContext
+     */
+    public function deserialize($header);
+
+    /**
+     * Convert a TraceContext to header string
+     *
+     * @param TraceContext $context
+     * @return string
+     */
+    public function serialize(TraceContext $context);
+}