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",
@@ -112,6 +113,7 @@ cc_library(
         "include/datadog/environment.h",
         "include/datadog/error.h",
         "include/datadog/event_scheduler.h",
+        "include/datadog/extracted_context.h",
         "include/datadog/expected.h",
         "include/datadog/http_client.h",
         "include/datadog/http_endpoint_calculation_mode.h",
@@ -132,6 +134,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/extracted_context.h

@@ -0,0 +1,30 @@
+#pragma once
+
+// Tracing context extracted from incoming distributed headers. Unlike `Span`,
+// this type holds only the propagation fields of the upstream context and does
+// not represent a locally-owned span.
+
+#include <cstdint>
+#include <string>
+
+#include "optional.h"
+#include "trace_id.h"
+
+namespace datadog {
+namespace tracing {
+
+struct ExtractedContext {
+  TraceID trace_id;
+  // The upstream span's ID (e.g. x-datadog-parent-id or traceparent
+  // parent-id field).
+  std::uint64_t span_id = 0;
+  // W3C tracestate, if present in the incoming headers.
+  Optional<std::string> tracestate;
+  // W3C trace flags byte, if present in the incoming traceparent header.
+  Optional<std::uint32_t> flags;
+  // Sampling priority extracted from the incoming headers.
+  Optional<int> sampling_priority;
+};
+
+}  // namespace tracing
+}  // namespace datadog

include/datadog/span.h

@@ -47,13 +47,15 @@
 
 #include "clock.h"
 #include "optional.h"
+#include "span_link.h"
 #include "string_view.h"
 #include "trace_id.h"
 #include "trace_source.h"
 
 namespace datadog {
 namespace tracing {
 
+struct ExtractedContext;
 struct InjectionOptions;
 class DictReader;
 class DictWriter;
@@ -166,6 +168,15 @@ 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 span link to this span, filled from the specified extracted
+  // distributed-tracing context.
+  void add_link(const ExtractedContext& ctx,
+                const SpanLinkAttributes& attrs = {});
+
   // 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,41 @@
+#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 {
+namespace 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 tracing
+}  // namespace datadog

src/datadog/span.cpp

@@ -1,7 +1,9 @@
 #include <datadog/dict_writer.h>
+#include <datadog/extracted_context.h>
 #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 +166,53 @@ 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;
+
+  // Capture injected headers (tracestate, traceparent flags) into a map.
+  struct : DictWriter {
+    std::unordered_map<std::string, std::string> map;
+    void set(StringView k, StringView v) override {
+      map[std::string(k)] = std::string(v);
+    }
+  } w;
+  linked.inject(w);
+  if (auto it = w.map.find("tracestate"); it != w.map.end()) {
+    link.tracestate = it->second;
+  }
+  if (auto it = w.map.find("traceparent"); it != w.map.end()) {
+    const auto& tp = it->second;
+    const auto pos = tp.rfind('-');
+    if (pos != std::string::npos && pos + 1 < tp.size()) {
+      try {
+        link.flags = static_cast<std::uint32_t>(
+            std::stoul(tp.substr(pos + 1), nullptr, 16));
+      } catch (...) {
+      }
+    }
+  }
+
+  data_->span_links.push_back(std::move(link));
+}
+
+void Span::add_link(const ExtractedContext& ctx,
+                    const SpanLinkAttributes& attrs) {
+  SpanLink link;
+  link.trace_id = ctx.trace_id;
+  link.span_id = ctx.span_id;
+  link.tracestate = ctx.tracestate;
+  link.attributes = attrs;
+  if (ctx.flags.has_value()) {
+    link.flags = ctx.flags;
+  } else if (ctx.sampling_priority.has_value()) {
+    link.flags = *ctx.sampling_priority > 0 ? 1u : 0u;
+  }
+  data_->span_links.push_back(std::move(link));
+}
+
 TraceSegment& Span::trace_segment() { return *trace_segment_; }
 
 const TraceSegment& Span::trace_segment() const { return *trace_segment_; }

src/datadog/span_data.cpp

@@ -75,7 +75,13 @@ void SpanData::apply_config(const SpanDefaults& defaults,
 
 Expected<void> msgpack_encode(std::string& destination, const SpanData& span) {
   // clang-format off
-  msgpack::pack_map(
+  const bool has_links = !span.span_links.empty();
+
+  // 12 always-present fields, plus span_links when there are any.
+  auto result = msgpack::pack_map(destination, has_links ? 13u : 12u);
+  if (!result) return result;
+
+  result = msgpack::pack_map_suffix(
       destination,
       "service", [&](auto& destination) {
          return msgpack::pack_string(destination, span.service);
@@ -131,6 +137,18 @@ Expected<void> msgpack_encode(std::string& destination, const SpanData& span) {
        }, "type", [&](auto& destination) {
          return msgpack::pack_string(destination, span.service_type);
        });
+  if (!result) return result;
+
+  if (has_links) {
+    result = msgpack::pack_string(destination, "span_links");
+    if (!result) return result;
+    result = msgpack::pack_array(
+        destination, span.span_links,
+        [](std::string& destination, const SpanLink& link) {
+          return msgpack_encode(destination, link);
+        });
+    if (!result) return result;
+  }
   // clang-format on
 
   return nullopt;

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,71 @@
+#include <datadog/span_link.h>
+
+#include <cstddef>
+#include <string>
+
+#include "msgpack.h"
+
+namespace datadog {
+namespace tracing {
+
+Expected<void> msgpack_encode(std::string& destination, const SpanLink& link) {
+  const bool has_trace_id_high = link.trace_id.high != 0;
+  const bool has_attributes = !link.attributes.empty();
+  const bool has_tracestate = link.tracestate && !link.tracestate->empty();
+  const bool has_flags = link.flags.has_value();
+
+  std::size_t size = 2;  // trace_id + span_id are always present
+  if (has_trace_id_high) ++size;
+  if (has_attributes) ++size;
+  if (has_tracestate) ++size;
+  if (has_flags) ++size;
+
+  auto result = msgpack::pack_map(destination, size);
+  if (!result) return result;
+
+  // trace_id (low 64 bits)
+  result = msgpack::pack_string(destination, "trace_id");
+  if (!result) return result;
+  msgpack::pack_integer(destination, link.trace_id.low);
+
+  if (has_trace_id_high) {
+    result = msgpack::pack_string(destination, "trace_id_high");
+    if (!result) return result;
+    msgpack::pack_integer(destination, link.trace_id.high);
+  }
+
+  result = msgpack::pack_string(destination, "span_id");
+  if (!result) return result;
+  msgpack::pack_integer(destination, link.span_id);
+
+  if (has_attributes) {
+    result = msgpack::pack_string(destination, "attributes");
+    if (!result) return result;
+    result =
+        msgpack::pack_map(destination, link.attributes,
+                          [](std::string& destination, const auto& value) {
+                            return msgpack::pack_string(destination, value);
+                          });
+    if (!result) return result;
+  }
+
+  if (has_tracestate) {
+    result = msgpack::pack_string(destination, "tracestate");
+    if (!result) return result;
+    result = msgpack::pack_string(destination, *link.tracestate);
+    if (!result) return result;
+  }
+
+  if (has_flags) {
+    result = msgpack::pack_string(destination, "flags");
+    if (!result) return result;
+    // 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 nullopt;
+}
+
+}  // namespace tracing
+}  // namespace datadog

test/CMakeLists.txt

@@ -33,6 +33,7 @@ add_executable(tests
     test_parse_util.cpp
     test_smoke.cpp
     test_span.cpp
+    test_span_link.cpp
     test_span_sampler.cpp
     test_trace_id.cpp
     test_trace_segment.cpp

test/system-tests/main.cpp

@@ -128,6 +128,10 @@ int main(int argc, char* argv[]) {
            [&handler](const httplib::Request& req, httplib::Response& res) {
              handler.on_manual_keep(req, res);
            });
+  svr.Post("/trace/span/add_link",
+           [&handler](const httplib::Request& req, httplib::Response& res) {
+             handler.on_add_link(req, res);
+           });
 
   // Not implemented
   svr.Post("/trace/span/set_metric",