Expand interface to support trace links (#523)

* Expand interface to support trace links

* Allow returning context with links

* Make variant public but const

* Remove friend declaration and extractVariant function

* Nonconst

alica_engine/include/engine/BasicBehaviour.h

@@ -84,7 +84,7 @@ class BasicBehaviour : private RunnableObject
 
     AgentId getOwnId() const;
 
-    void setTracing(TracingType type, std::function<std::optional<std::string>(const BasicBehaviour*)> customTraceContextGetter = {})
+    void setTracing(TracingType type, std::function<tracing::SpanStartOptions(const BasicBehaviour*)> customTraceContextGetter = {})
     {
         if (customTraceContextGetter) {
             RunnableObject::setTracing(
@@ -93,7 +93,14 @@ class BasicBehaviour : private RunnableObject
             RunnableObject::setTracing(type, {});
         }
     }
-
+    void setTracing(TracingType type, std::function<std::optional<std::string>(const BasicBehaviour*)> customTraceContextGetter)
+    {
+        setTracing(type, [this, inner = std::move(customTraceContextGetter)](const BasicBehaviour*) {
+            tracing::SpanStartOptions options;
+            options.parentContext = inner(this);
+            return options;
+        });
+    }
     void setSuccess();
     void setFailure();
 

alica_engine/include/engine/BasicPlan.h

@@ -53,7 +53,7 @@ class BasicPlan : private RunnableObject
 protected:
     using RunnableObject::getTraceFactory;
 
-    void setTracing(TracingType type, std::function<std::optional<std::string>(const BasicPlan*)> customTraceContextGetter = {})
+    void setTracing(TracingType type, std::function<tracing::SpanStartOptions(const BasicPlan*)> customTraceContextGetter = {})
     {
         if (customTraceContextGetter) {
             RunnableObject::setTracing(
@@ -62,6 +62,14 @@ class BasicPlan : private RunnableObject
             RunnableObject::setTracing(type, {});
         }
     }
+    void setTracing(TracingType type, std::function<std::optional<std::string>(const BasicPlan*)> customTraceContextGetter)
+    {
+        setTracing(type, [this, inner = std::move(customTraceContextGetter)](const BasicPlan*) -> tracing::SpanStartOptions {
+            tracing::SpanStartOptions options;
+            options.parentContext = inner(this);
+            return options;
+        });
+    }
 
     virtual void onInit(){};
     virtual void run(){};

alica_engine/include/engine/IAlicaTrace.h

@@ -8,6 +8,7 @@
 #include <unordered_map>
 #include <utility>
 #include <variant>
+#include <vector>
 
 namespace alica
 {
@@ -23,8 +24,6 @@ class IAlicaTrace
 public:
     class TraceValue
     {
-        friend IAlicaTrace;
-
         using Variant = std::variant<bool, long long int, unsigned long long int, double, std::string_view>;
 
     public:
@@ -34,7 +33,6 @@ class IAlicaTrace
         {
         }
 
-    private:
         Variant variant;
     };
 
@@ -48,19 +46,34 @@ class IAlicaTrace
     // leave the trace in a valid but unspecified state. Calling context on a finished trace is a valid operation
     virtual void finish() = 0;
     virtual std::string context() const = 0;
+};
 
-protected:
-    template <typename V>
-    static decltype(auto) extractVariant(V&& trace_value)
-    {
-        return (std::forward<V>(trace_value).variant);
-    }
+namespace tracing
+{
+struct SpanLink
+{
+    std::string context;
+    // Warning:  Ensure string_views in attributes are valid for the lifetime of the span link
+    std::unordered_map<std::string, IAlicaTrace::TraceValue> attributes;
 };
 
+struct SpanStartOptions
+{
+    std::optional<std::string> parentContext;
+    std::vector<SpanLink> links;
+};
+} // namespace tracing
+
 class IAlicaTraceFactory
 {
 public:
-    virtual std::unique_ptr<IAlicaTrace> create(const std::string& opName, std::optional<const std::string> parent = std::nullopt) const = 0;
+    // Two argument version of create.  Deprecated.
+    virtual std::unique_ptr<IAlicaTrace> create(const std::string& opName, std::optional<const std::string> parent = std::nullopt) const { return nullptr; }
+    virtual std::unique_ptr<IAlicaTrace> create(const std::string& opName, const tracing::SpanStartOptions& options) const
+    {
+        // Concrete implementation provided for backwards compatibility
+        return create(opName, options.parentContext);
+    }
     virtual void setGlobalContext(const std::string& globalContext) = 0;
     virtual void unsetGlobalContext() = 0;
     virtual ~IAlicaTraceFactory() = default;

alica_engine/include/engine/RunnableObject.h

@@ -58,7 +58,7 @@ class TraceRunnableObject
 
     // Set the tracing type for this runnable object. customTraceContextGetter is required for custom tracing
     // & this method will be called to get the parent trace context before initialiseParameters is called
-    void setTracing(TracingType type, std::function<std::optional<std::string>()> customTraceContextGetter = {});
+    void setTracing(TracingType type, std::function<tracing::SpanStartOptions()> customTraceContextGetter = {});
     void setupTraceContext(const std::string& name, RunningPlan* rp);
     void cleanupTraceContext();
     void traceInitCall();
@@ -72,7 +72,7 @@ class TraceRunnableObject
     TracingType _tracingType;
     bool _runTraced; // True if the behaviour/plan's run method has already been logged in the trace
     const IAlicaTraceFactory* _tf;
-    std::function<std::optional<std::string>()> _customTraceContextGetter;
+    std::function<tracing::SpanStartOptions()> _customTraceContextGetter;
     std::unique_ptr<IAlicaTrace> _trace;
     const std::string& _name;
 };
@@ -94,10 +94,11 @@ class RunnableObject
     virtual void doRun() = 0;
     virtual void doTerminate() = 0;
 
-    void setTracing(TracingType type, std::function<std::optional<std::string>()> customTraceContextGetter = {})
+    void setTracing(TracingType type, std::function<tracing::SpanStartOptions()> customTraceContextGetter = {})
     {
         _runnableObjectTracer.setTracing(type, customTraceContextGetter);
     }
+
     const std::string& getName() const { return _name; };
     IAlicaTrace* getTrace() const { return _runnableObjectTracer.getTrace(); };
     // Helper to allow applications to generate their own trace.

alica_engine/src/engine/RunnableObject.cpp

@@ -168,7 +168,7 @@ void RunnableObject::handleException(const std::string& exceptionOriginMethod, s
 }
 
 // Tracing methods
-void TraceRunnableObject::setTracing(TracingType type, std::function<std::optional<std::string>()> customTraceContextGetter)
+void TraceRunnableObject::setTracing(TracingType type, std::function<tracing::SpanStartOptions()> customTraceContextGetter)
 {
     _tracingType = type;
     _customTraceContextGetter = std::move(customTraceContextGetter);

alica_tests/include/alica_tests/TestTracing.h

@@ -62,7 +62,7 @@ class AlicaTestTrace : public alica::IAlicaTrace
                     ss << v;
                     return std::move(ss).str();
                 },
-                extractVariant(val));
+                val.variant);
     }
 };
 

supplementary/alica_tracing/src/tracing/Trace.cpp

@@ -57,7 +57,7 @@ Trace::~Trace()
 
 void Trace::setTag(std::string_view key, TraceValue value)
 {
-    _rawTrace->SetTag(prepareStringView(key), prepareRawTraceValue(extractVariant(std::move(value))));
+    _rawTrace->SetTag(prepareStringView(key), prepareRawTraceValue(std::move(value.variant)));
 }
 
 void Trace::setTag(const std::string& key, const RawTraceValue& value)
@@ -71,7 +71,7 @@ void Trace::log(const std::unordered_map<std::string_view, TraceValue>& fields)
     RawFields raw_fields;
     raw_fields.reserve(fields.size());
     std::transform(begin(fields), end(fields), std::back_inserter(raw_fields),
-            [](const auto& v) { return std::make_pair(prepareStringView(v.first), prepareRawTraceValue(extractVariant(v.second))); });
+            [](const auto& v) { return std::make_pair(prepareStringView(v.first), prepareRawTraceValue(v.second.variant)); });
     _rawTrace->Log(opentracing::SystemClock::now(), raw_fields);
 }