feat(tracing): add span link support

BUILD.bazel

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

CMakeLists.txt

@@ -160,6 +160,7 @@ target_sources(dd-trace-cpp-objects
       include/datadog/span.h
       include/datadog/span_config.h
       include/datadog/span_defaults.h
+      include/datadog/span_link.h
       include/datadog/span_matcher.h
       include/datadog/span_sampler_config.h
       include/datadog/string_view.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

@@ -47,6 +47,7 @@
 
 #include "clock.h"
 #include "optional.h"
+#include "span_link.h"
 #include "string_view.h"
 #include "trace_id.h"
 #include "trace_source.h"
@@ -166,6 +167,13 @@ class Span {
   // Specifies the product (AppSec, DBM) that created this span.
   void set_source(Source);
 
+  // Add a span link to this span, filled from the specified live span.
+  // The linked span's trace ID, span ID, tracestate, and trace flags are
+  // populated automatically. `attrs` is optional user-supplied attributes.
+  void add_link(const Span& linked, const SpanLinkAttributes& attrs = {});
+  // Add a pre-built span link to this span.
+  void add_link(const SpanLink& link);
+
   // 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_link.h

@@ -0,0 +1,39 @@
+#pragma once
+
+// This component defines `SpanLink`, a causal association between the span that
+// owns the link and another span (possibly in another trace). Span links carry
+// the linked span's identifiers plus optional W3C tracestate, trace flags, and
+// arbitrary string attributes. They are serialized into the owning span under
+// the `span_links` key in a format shared by all Datadog tracers.
+
+#include <cstdint>
+#include <string>
+#include <unordered_map>
+
+#include "expected.h"
+#include "optional.h"
+#include "trace_id.h"
+
+namespace datadog::tracing {
+
+// Convenience alias: the map type used for span link user attributes.
+using SpanLinkAttributes = std::unordered_map<std::string, std::string>;
+
+struct SpanLink {
+  // 128-bit trace ID of the linked span.
+  TraceID trace_id;
+  // The linked span's ID.
+  std::uint64_t span_id = 0;
+  // W3C `tracestate` header value from the linked context, if any.
+  Optional<std::string> tracestate;
+  // Additional string attributes associated with the link.
+  std::unordered_map<std::string, std::string> attributes;
+  // W3C trace flags from the linked context, if any.
+  Optional<std::uint32_t> flags;
+};
+
+// Append to the specified `destination` the MessagePack representation of the
+// specified `link`.
+Expected<void> msgpack_encode(std::string& destination, const SpanLink& link);
+
+}  // namespace datadog::tracing

src/datadog/span.cpp

@@ -2,6 +2,7 @@
 #include <datadog/optional.h>
 #include <datadog/span.h>
 #include <datadog/span_config.h>
+#include <datadog/span_link.h>
 #include <datadog/string_view.h>
 #include <datadog/trace_segment.h>
 
@@ -164,6 +165,45 @@ void Span::set_source(Source source) {
                                             to_tag(source));
 }
 
+void Span::add_link(const Span& linked, const SpanLinkAttributes& attrs) {
+  SpanLink link;
+  link.trace_id = linked.trace_id();
+  link.span_id = linked.id();
+  link.attributes = attrs;
+
+  // inject linked span to get its tracestate, traceparent flags)
+  struct : DictWriter {
+    std::unordered_map<std::string, std::string> map;
+    void set(StringView k, StringView v) override {
+      if (k == "tracestate" || k == "traceparent") {
+        map[std::string(k)] = std::string(v);
+      }
+    }
+  } injected_headers;
+  linked.inject(injected_headers);
+
+  if (auto it = injected_headers.map.find("tracestate");
+      it != injected_headers.map.end()) {
+    link.tracestate = it->second;
+  }
+  if (auto it = injected_headers.map.find("traceparent");
+      it != injected_headers.map.end()) {
+    const auto& traceparent = it->second;
+    const auto pos = traceparent.rfind('-');
+    if (pos != std::string::npos && pos + 1 < traceparent.size()) {
+      try {
+        link.flags = static_cast<std::uint32_t>(
+            std::stoul(traceparent.substr(pos + 1), nullptr, 16));
+      } catch (...) {
+      }
+    }
+  }
+
+  data_->span_links.push_back(std::move(link));
+}
+
+void Span::add_link(const SpanLink& link) { data_->span_links.push_back(link); }
+
 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

@@ -6,6 +6,7 @@
 #include <datadog/clock.h>
 #include <datadog/expected.h>
 #include <datadog/optional.h>
+#include <datadog/span_link.h>
 #include <datadog/string_view.h>
 #include <datadog/trace_id.h>
 
@@ -33,6 +34,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;

src/datadog/span_link.cpp

@@ -0,0 +1,73 @@
+#include <datadog/span_link.h>
+
+#include <algorithm>
+#include <array>
+#include <cstddef>
+#include <functional>
+#include <string>
+#include <tuple>
+
+#include "msgpack.h"
+
+namespace datadog::tracing {
+
+Expected<void> msgpack_encode(std::string& destination, const SpanLink& link) {
+  // array of (is_present, field_name, pack_function)
+  const std::array<
+      std::tuple<bool, StringView, std::function<Expected<void>(std::string&)>>,
+      6>
+      fields{{
+          {true, "trace_id",
+           [&](std::string& destination) {
+             msgpack::pack_integer(destination, link.trace_id.low);
+             return Expected<void>{};
+           }},
+          {true, "span_id",
+           [&](std::string& destination) {
+             msgpack::pack_integer(destination, link.span_id);
+             return Expected<void>{};
+           }},
+          {link.trace_id.high != 0, "trace_id_high",
+           [&](std::string& destination) {
+             msgpack::pack_integer(destination, link.trace_id.high);
+             return Expected<void>{};
+           }},
+          {!link.attributes.empty(), "attributes",
+           [&](std::string& destination) {
+             return msgpack::pack_map(
+                 destination, link.attributes,
+                 [](std::string& destination, const auto& value) {
+                   return msgpack::pack_string(destination, value);
+                 });
+           }},
+          {link.tracestate.has_value() && !link.tracestate->empty(),
+           "tracestate",
+           [&](std::string& destination) {
+             return msgpack::pack_string(destination, *link.tracestate);
+           }},
+          {link.flags.has_value(), "flags",
+           [&](std::string& destination) {
+             // The high bit marks "flags is present" so a receiver can
+             // distinguish an explicit value of 0 from an omitted field.
+             msgpack::pack_integer(destination,
+                                   std::uint64_t(*link.flags | (1u << 31)));
+             return Expected<void>{};
+           }},
+      }};
+
+  const auto size = std::count_if(fields.begin(), fields.end(),
+                                  [](const auto& f) { return std::get<0>(f); });
+
+  auto result = msgpack::pack_map(destination, size);
+  if (!result) return result;
+
+  for (const auto& [present, field, pack] : fields) {
+    if (present) {
+      result = msgpack::pack_map_suffix(destination, field, pack);
+      if (!result) break;
+    }
+  }
+  return result;
+}
+
+}  // namespace datadog::tracing