Allow collecting time events/links (#171)

* Add tests for ability to add annotations, links, message events

* Tracers return SpanData

* Add setters to RequestHandler

* Implement SpanEventHandler to keep extension spans in sync

* Remove extension config file that should be ignored

* Add documentation

Author: chingor13

ext/.gitignore

@@ -15,6 +15,7 @@ config.status
 config.sub
 configure
 configure.in
+configure.ac
 install-sh
 libtool
 ltmain.sh

ext/opencensus_trace_span.c

@@ -97,6 +97,7 @@
 #include "opencensus_trace_link.h"
 #include "opencensus_trace_message_event.h"
 #include "Zend/zend_alloc.h"
+#include "Zend/zend_variables.h"
 
 zend_class_entry* opencensus_trace_span_ce = NULL;
 
@@ -498,6 +499,9 @@ int opencensus_trace_span_add_annotation(opencensus_trace_span_t *span, zend_str
     opencensus_trace_annotation_t *annotation = opencensus_trace_annotation_alloc();
     annotation->time_event.time = opencensus_now();
     annotation->description = zend_string_copy(description);
+    if (options != NULL) {
+        zend_hash_merge(Z_ARR(annotation->options), Z_ARR_P(options), zval_add_ref, 1);
+    }
 
     zend_hash_next_index_insert_ptr(span->time_events, annotation);
     return SUCCESS;
@@ -509,6 +513,9 @@ int opencensus_trace_span_add_link(opencensus_trace_span_t *span, zend_string *t
     opencensus_trace_link_t *link = opencensus_trace_link_alloc();
     link->trace_id = zend_string_copy(trace_id);
     link->span_id = zend_string_copy(span_id);
+    if (options != NULL) {
+        zend_hash_merge(Z_ARR(link->options), Z_ARR_P(options), zval_add_ref, 1);
+    }
 
     zend_hash_next_index_insert_ptr(span->links, link);
     return FAILURE;
@@ -521,6 +528,9 @@ int opencensus_trace_span_add_message_event(opencensus_trace_span_t *span, zend_
     message_event->time_event.time = opencensus_now();
     message_event->type = zend_string_copy(type);
     message_event->id = zend_string_copy(id);
+    if (options != NULL) {
+        zend_hash_merge(Z_ARR(message_event->options), Z_ARR_P(options), zval_add_ref, 1);
+    }
 
     zend_hash_next_index_insert_ptr(span->time_events, message_event);
     return SUCCESS;
@@ -569,6 +579,8 @@ int opencensus_trace_span_apply_span_options(opencensus_trace_span_t *span, zval
             if (Z_TYPE_P(v) == IS_FALSE) {
                 span->same_process_as_parent_span = 0;
             }
+        } else if (strcmp(ZSTR_VAL(k), "stackTrace") == 0) {
+            ZVAL_COPY(&span->stackTrace, v);
         }
     } ZEND_HASH_FOREACH_END();
     return SUCCESS;

ext/tests/annotations.phpt

@@ -4,7 +4,11 @@ OpenCensus Trace: Test setting annotations
 <?php
 
 opencensus_trace_begin('root', ['spanId' => '1234']);
-opencensus_trace_add_annotation('foo');
+opencensus_trace_add_annotation('foo', [
+    'attributes' => [
+        'foo' => 'bar'
+    ]
+]);
 opencensus_trace_begin('inner', []);
 opencensus_trace_add_annotation('asdf', ['spanId' => '1234']);
 opencensus_trace_add_annotation('abc');
@@ -29,6 +33,11 @@ Array
             [time:protected] => %d.%d
             [options:protected] => Array
                 (
+                    [attributes] => Array
+                        (
+                            [foo] => bar
+                        )
+
                 )
 
         )
@@ -39,6 +48,7 @@ Array
             [time:protected] => %d.%d
             [options:protected] => Array
                 (
+                    [spanId] => 1234
                 )
 
         )

ext/tests/links.phpt

@@ -4,7 +4,9 @@ OpenCensus Trace: Test setting links
 <?php
 
 opencensus_trace_begin('root', ['spanId' => '1234']);
-opencensus_trace_add_link('traceId', 'spanId');
+opencensus_trace_add_link('traceId', 'spanId', [
+    'type' => 'CHILD_LINKED_SPAN'
+]);
 opencensus_trace_begin('inner', []);
 opencensus_trace_add_link('traceId', 'spanId', ['spanId' => '1234']);
 opencensus_trace_add_link('traceId', 'spanId');
@@ -29,6 +31,7 @@ Array
             [spanId:protected] => spanId
             [options:protected] => Array
                 (
+                    [type] => CHILD_LINKED_SPAN
                 )
 
         )
@@ -39,6 +42,7 @@ Array
             [spanId:protected] => spanId
             [options:protected] => Array
                 (
+                    [spanId] => 1234
                 )
 
         )

ext/tests/message_events.phpt

@@ -4,7 +4,9 @@ OpenCensus Trace: Test setting message events
 <?php
 
 opencensus_trace_begin('root', ['spanId' => '1234']);
-opencensus_trace_add_message_event('TYPE_UNSPECIFIED', 'some id');
+opencensus_trace_add_message_event('TYPE_UNSPECIFIED', 'some id', [
+    'compressedSize' => 123
+]);
 opencensus_trace_begin('inner', []);
 opencensus_trace_add_message_event('TYPE_UNSPECIFIED', 'some id', ['spanId' => '1234']);
 opencensus_trace_add_message_event('TYPE_UNSPECIFIED', 'some id');
@@ -30,6 +32,7 @@ Array
             [time:protected] => %d.%d
             [options:protected] => Array
                 (
+                    [compressedSize] => 123
                 )
 
         )
@@ -41,6 +44,7 @@ Array
             [time:protected] => %d.%d
             [options:protected] => Array
                 (
+                    [spanId] => 1234
                 )
 
         )

src/Trace/EventHandler/NullEventHandler.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace OpenCensus\Trace\EventHandler;
+
+use OpenCensus\Trace\Annotation;
+use OpenCensus\Trace\Link;
+use OpenCensus\Trace\MessageEvent;
+use OpenCensus\Trace\Span;
+use OpenCensus\Trace\TimeEvent;
+
+/**
+ * This implementation of the SpanEventHandlerInterface does nothing.
+ */
+class NullEventHandler implements SpanEventHandlerInterface
+{
+    /**
+     * Triggers when an attribute is added to a span.
+     *
+     * @param Span $span The span the attribute was added to
+     * @param string $attribute The name of the attribute added
+     * @param string $value The attribute value
+     */
+    public function attributeAdded(Span $span, $attribute, $value)
+    {
+    }
+
+    /**
+     * Triggers when a link is added to a span.
+     *
+     * @param Span $span The span the link was added to
+     * @param Link $link The link added to the span
+     */
+    public function linkAdded(Span $span, Link $link)
+    {
+    }
+
+    /**
+     * Triggers when a time event is added to a span.
+     *
+     * @param Span $span The span the time event was added to
+     * @param TimeEvent $timeEvent The time event added to the span
+     */
+    public function timeEventAdded(Span $span, TimeEvent $timeEvent)
+    {
+    }
+}

src/Trace/EventHandler/SpanEventHandlerInterface.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace OpenCensus\Trace\EventHandler;
+
+use OpenCensus\Trace\Link;
+use OpenCensus\Trace\Span;
+use OpenCensus\Trace\TimeEvent;
+
+/**
+ * This interface defines events that are triggered when a Span is updated.
+ */
+interface SpanEventHandlerInterface
+{
+    /**
+     * Triggers when an attribute is added to a span.
+     *
+     * @param Span $span The span the attribute was added to
+     * @param string $attribute The name of the attribute added
+     * @param string $value The attribute value
+     */
+    public function attributeAdded(Span $span, $attribute, $value);
+
+    /**
+     * Triggers when a link is added to a span.
+     *
+     * @param Span $span The span the link was added to
+     * @param Link $link The link added to the span
+     */
+    public function linkAdded(Span $span, Link $link);
+
+    /**
+     * Triggers when a time event is added to a span.
+     *
+     * @param Span $span The span the time event was added to
+     * @param TimeEvent $timeEvent The time event added to the span
+     */
+    public function timeEventAdded(Span $span, TimeEvent $timeEvent);
+}

src/Trace/RequestHandler.php

@@ -138,11 +138,7 @@ public function onExit()
 
         $this->scope->close();
 
-        // Fetch the SpanData of all the collected Spans
-        $spans = array_map(function (Span $span) {
-            return $span->spanData();
-        }, $this->tracer->spans());
-        $this->exporter->export($spans);
+        $this->exporter->export($this->tracer->spans());
     }
 
     /**
@@ -210,6 +206,59 @@ public function addAttribute($attribute, $value, $options = [])
         $this->tracer->addAttribute($attribute, $value, $options);
     }
 
+    /**
+     * Add an annotation to the provided Span
+     *
+     * @param string $description
+     * @param array $options [optional] Configuration options.
+     *
+     *      @type Span $span The span to add the annotation to.
+     *      @type array $attributes Attributes for this annotation.
+     *      @type \DateTimeInterface|int|float $time The time of this event.
+     */
+    public function addAnnotation($description, $options = [])
+    {
+        $this->tracer->addAnnotation($description, $options);
+    }
+
+    /**
+     * Add a link to the provided Span
+     *
+     * @param string $traceId
+     * @param string $spanId
+     * @param array $options [optional] Configuration options.
+     *
+     *      @type Span $span The span to add the link to.
+     *      @type string $type The relationship of the current span relative to
+     *            the linked span: child, parent, or unspecified.
+     *      @type array $attributes Attributes for this annotation.
+     *      @type \DateTimeInterface|int|float $time The time of this event.
+     */
+    public function addLink($traceId, $spanId, $options = [])
+    {
+        $this->tracer->addLink($traceId, $spanId, $options);
+    }
+
+    /**
+     * Add an message event to the provided Span
+     *
+     * @param string $type
+     * @param string $id
+     * @param array $options [optional] Configuration options.
+     *
+     *      @type Span $span The span to add the message event to.
+     *      @type int $uncompressedSize The number of uncompressed bytes sent or
+     *            received.
+     *      @type int $compressedSize The number of compressed bytes sent or
+     *            received. If missing assumed to be the same size as
+     *            uncompressed.
+     *      @type \DateTimeInterface|int|float $time The time of this event.
+     */
+    public function addMessageEvent($type, $id, $options)
+    {
+        $this->tracer->addMessageEvent($type, $id, $options);
+    }
+
     public function addCommonRequestAttributes(array $headers)
     {
         $responseCode = http_response_code();