feat(tracing): add span link support

BUILD.bazel

@@ -55,6 +55,8 @@ cc_library(
         "src/datadog/span.cpp",
         "src/datadog/span_data.cpp",
         "src/datadog/span_data.h",
+        "src/datadog/span_link.cpp",
+        "src/datadog/span_link.h",
         "src/datadog/span_matcher.cpp",
         "src/datadog/span_sampler.cpp",
         "src/datadog/span_sampler.h",
@@ -131,6 +133,7 @@ cc_library(
         "include/datadog/sampling_priority.h",
         "include/datadog/span.h",
         "include/datadog/span_config.h",
+        "include/datadog/span_context.h",
         "include/datadog/span_defaults.h",
         "include/datadog/span_matcher.h",
         "include/datadog/span_sampler_config.h",

CMakeLists.txt

@@ -159,6 +159,7 @@ target_sources(dd-trace-cpp-objects
       include/datadog/sampling_priority.h
       include/datadog/span.h
       include/datadog/span_config.h
+      include/datadog/span_context.h
       include/datadog/span_defaults.h
       include/datadog/span_matcher.h
       include/datadog/span_sampler_config.h
@@ -203,6 +204,7 @@ target_sources(dd-trace-cpp-objects
     src/datadog/runtime_id.cpp
     src/datadog/span.cpp
     src/datadog/span_data.cpp
+    src/datadog/span_link.cpp
     src/datadog/span_matcher.cpp
     src/datadog/span_sampler_config.cpp
     src/datadog/span_sampler.cpp

include/datadog/span.h

@@ -43,9 +43,12 @@
 #include <cstdint>
 #include <functional>
 #include <memory>
+#include <string>
+#include <unordered_map>
 
 #include "clock.h"
 #include "optional.h"
+#include "span_context.h"
 #include "string_view.h"
 #include "trace_id.h"
 #include "trace_source.h"
@@ -60,6 +63,9 @@ struct SpanConfig;
 struct SpanData;
 class TraceSegment;
 
+// The map type used for user-supplied span-link attributes.
+using SpanLinkAttributes = std::unordered_map<std::string, std::string>;
+
 class Span {
   std::shared_ptr<TraceSegment> trace_segment_;
   SpanData* data_;
@@ -165,6 +171,14 @@ class Span {
   // Specifies the product (AppSec, DBM) that created this span.
   void set_source(Source);
 
+  // Return this span's identifying and propagation state. This does not make a
+  // sampling decision when one has not already been made.
+  SpanContext context() const;
+
+  // Add a link to this span.
+  void add_link(const SpanContext& context,
+                const SpanLinkAttributes& attributes = {});
+
   // Write information about this span and its trace into the specified `writer`
   // using all of the configured injection propagation styles.
   void inject(DictWriter& writer) const;

include/datadog/span_context.h

@@ -0,0 +1,34 @@
+#pragma once
+
+// This component defines `SpanContext`, the identifying and propagation state
+// of a span. It can be supplied to `Span::add_link` to associate a span with a
+// span in this or another trace.
+
+#include <cstdint>
+#include <string>
+
+#include "trace_id.h"
+
+namespace datadog::tracing {
+
+class SpanContext {
+ public:
+  // 128-bit trace ID of the span.
+  TraceID trace_id;
+  // ID of the span within its trace.
+  std::uint64_t span_id;
+  // W3C `tracestate` header value, if any.
+  Optional<std::string> tracestate;
+  // W3C trace flags, if any.
+  Optional<std::uint32_t> flags;
+
+  SpanContext(TraceID trace_id, std::uint64_t span_id,
+              Optional<std::string> tracestate = nullopt,
+              Optional<std::uint32_t> flags = nullopt)
+      : trace_id(trace_id),
+        span_id(span_id),
+        tracestate(tracestate),
+        flags(flags) {}
+};
+
+}  // namespace datadog::tracing

include/datadog/trace_segment.h

@@ -56,6 +56,8 @@ class SpanSampler;
 class TraceSampler;
 class ConfigManager;
 
+using W3CLinkContext = std::pair<std::string, std::uint32_t>;
+
 class TraceSegment {
   mutable std::mutex mutex_;
 
@@ -75,8 +77,8 @@ class TraceSegment {
   std::vector<std::unique_ptr<SpanData>> spans_;
   std::size_t num_finished_spans_;
   Optional<SamplingDecision> sampling_decision_;
-  Optional<std::string> additional_w3c_tracestate_;
-  Optional<std::string> additional_datadog_w3c_tracestate_;
+  const Optional<std::string> additional_w3c_tracestate_;
+  const Optional<std::string> additional_datadog_w3c_tracestate_;
 
   std::shared_ptr<ConfigManager> config_manager_;
 
@@ -108,6 +110,14 @@ class TraceSegment {
   const Optional<std::string>& origin() const;
   Optional<SamplingDecision> sampling_decision() const;
 
+  // Return the W3C tracestate encoding and derived trace flags for `span`,
+  // based on this segment's sampling decision. Unlike `inject`, this never
+  // makes a sampling decision if one hasn't been made yet -- it returns
+  // `nullopt` instead of forcing (and thereby permanently finalizing) one.
+  // Used by `Span::context` without prematurely deciding sampling for the
+  // trace.
+  Optional<W3CLinkContext> w3c_link_context(const SpanData& span) const;
+
   Logger& logger() const;
 
   // Inject trace context for the specified `span` into the specified `writer`,

src/datadog/span.cpp

@@ -164,6 +164,23 @@ void Span::set_source(Source source) {
                                             to_tag(source));
 }
 
+SpanContext Span::context() const {
+  SpanContext context{trace_id(), id()};
+
+  if (Optional<W3CLinkContext> w3c_context =
+          trace_segment_->w3c_link_context(*data_)) {
+    context.tracestate = std::move(w3c_context->first);
+    context.flags = w3c_context->second;
+  }
+
+  return context;
+}
+
+void Span::add_link(const SpanContext& context,
+                    const SpanLinkAttributes& attributes) {
+  data_->span_links.emplace_back(context, attributes);
+}
+
 TraceSegment& Span::trace_segment() { return *trace_segment_; }
 
 const TraceSegment& Span::trace_segment() const { return *trace_segment_; }

src/datadog/span_data.cpp

@@ -7,6 +7,8 @@
 
 #include <cassert>
 #include <cstddef>
+#include <string>
+#include <vector>
 
 #include "msgpack.h"
 #include "tags.h"
@@ -74,66 +76,86 @@ void SpanData::apply_config(const SpanDefaults& defaults,
 }
 
 Expected<void> msgpack_encode(std::string& destination, const SpanData& span) {
-  // clang-format off
-  msgpack::pack_map(
-      destination,
-      "service", [&](auto& destination) {
-         return msgpack::pack_string(destination, span.service);
-       },
-      "name", [&](auto& destination) {
-         return msgpack::pack_string(destination, span.name);
-       },
-      "resource", [&](auto& destination) {
-         return msgpack::pack_string(destination, span.resource);
-       },
-      "trace_id", [&](auto& destination) {
-         msgpack::pack_integer(destination, span.trace_id.low);
-         return Expected<void>{};
-       },
-      "span_id", [&](auto& destination) {
-         msgpack::pack_integer(destination, span.span_id);
-         return Expected<void>{};
-       },
-      "parent_id", [&](auto& destination) {
-         msgpack::pack_integer(destination, span.parent_id);
-         return Expected<void>{};
-       },
-      "start", [&](auto& destination) {
-         msgpack::pack_integer(
-             destination, std::uint64_t(std::chrono::duration_cast<std::chrono::nanoseconds>(
-                              span.start.wall.time_since_epoch())
-                              .count()));
-         return Expected<void>{};
-       },
-      "duration", [&](auto& destination) {
-         msgpack::pack_integer(
-             destination,
-             std::uint64_t(std::chrono::duration_cast<std::chrono::nanoseconds>(span.duration)
-                 .count()));
-        return Expected<void>{};
-       },
-      "error", [&](auto& destination) {
-         msgpack::pack_integer(destination, std::int32_t(span.error));
-         return Expected<void>{};
-       },
-      "meta", [&](auto& destination) {
-         return msgpack::pack_map(destination, span.tags,
-                           [](std::string& destination, const auto& value) {
-                             return msgpack::pack_string(destination, value);
-                           });
-       }, "metrics",
-       [&](auto& destination) {
-         return msgpack::pack_map(destination, span.numeric_tags,
-                           [](std::string& destination, const auto& value) {
-                             msgpack::pack_double(destination, value);
-                             return Expected<void>{};
-                           });
-       }, "type", [&](auto& destination) {
-         return msgpack::pack_string(destination, span.service_type);
-       });
-  // clang-format on
-
-  return nullopt;
+  auto pack_service = [&](auto& destination) {
+    return msgpack::pack_string(destination, span.service);
+  };
+  auto pack_name = [&](auto& destination) {
+    return msgpack::pack_string(destination, span.name);
+  };
+  auto pack_resource = [&](auto& destination) {
+    return msgpack::pack_string(destination, span.resource);
+  };
+  auto pack_trace_id = [&](auto& destination) {
+    msgpack::pack_integer(destination, span.trace_id.low);
+    return Expected<void>{};
+  };
+  auto pack_span_id = [&](auto& destination) {
+    msgpack::pack_integer(destination, span.span_id);
+    return Expected<void>{};
+  };
+  auto pack_parent_id = [&](auto& destination) {
+    msgpack::pack_integer(destination, span.parent_id);
+    return Expected<void>{};
+  };
+  auto pack_start = [&](auto& destination) {
+    msgpack::pack_integer(
+        destination,
+        std::uint64_t(std::chrono::duration_cast<std::chrono::nanoseconds>(
+                          span.start.wall.time_since_epoch())
+                          .count()));
+    return Expected<void>{};
+  };
+  auto pack_duration = [&](auto& destination) {
+    msgpack::pack_integer(
+        destination,
+        std::uint64_t(
+            std::chrono::duration_cast<std::chrono::nanoseconds>(span.duration)
+                .count()));
+    return Expected<void>{};
+  };
+  auto pack_error = [&](auto& destination) {
+    msgpack::pack_integer(destination, std::int32_t(span.error));
+    return Expected<void>{};
+  };
+  auto pack_meta = [&](auto& destination) {
+    return msgpack::pack_map(destination, span.tags,
+                             [](std::string& destination, const auto& value) {
+                               return msgpack::pack_string(destination, value);
+                             });
+  };
+  auto pack_metrics = [&](auto& destination) {
+    return msgpack::pack_map(destination, span.numeric_tags,
+                             [](std::string& destination, const auto& value) {
+                               msgpack::pack_double(destination, value);
+                               return Expected<void>{};
+                             });
+  };
+  auto pack_type = [&](auto& destination) {
+    return msgpack::pack_string(destination, span.service_type);
+  };
+
+  if (span.span_links.empty()) {
+    return msgpack::pack_map(
+        destination, "service", pack_service, "name", pack_name, "resource",
+        pack_resource, "trace_id", pack_trace_id, "span_id", pack_span_id,
+        "parent_id", pack_parent_id, "start", pack_start, "duration",
+        pack_duration, "error", pack_error, "meta", pack_meta, "metrics",
+        pack_metrics, "type", pack_type);
+  } else {
+    auto pack_span_links = [&](auto& destination) {
+      return msgpack::pack_array(
+          destination, span.span_links,
+          [](std::string& destination, const SpanLink& link) {
+            return msgpack_encode(destination, link);
+          });
+    };
+    return msgpack::pack_map(
+        destination, "service", pack_service, "name", pack_name, "resource",
+        pack_resource, "trace_id", pack_trace_id, "span_id", pack_span_id,
+        "parent_id", pack_parent_id, "start", pack_start, "duration",
+        pack_duration, "error", pack_error, "meta", pack_meta, "metrics",
+        pack_metrics, "type", pack_type, "span_links", pack_span_links);
+  }
 }
 
 Expected<void> msgpack_encode(

src/datadog/span_data.h

@@ -14,6 +14,8 @@
 #include <unordered_map>
 #include <vector>
 
+#include "span_link.h"
+
 namespace datadog {
 namespace tracing {
 
@@ -33,6 +35,7 @@ struct SpanData {
   bool error = false;
   std::unordered_map<std::string, std::string> tags;
   std::unordered_map<std::string, double> numeric_tags;
+  std::vector<SpanLink> span_links;
 
   Optional<StringView> environment() const;
   Optional<StringView> version() const;