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

@@ -47,6 +47,7 @@
 
 #include "clock.h"
 #include "optional.h"
+#include "span_context.h"
 #include "string_view.h"
 #include "trace_id.h"
 #include "trace_source.h"
@@ -166,6 +167,15 @@ 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 span link to this span using the specified context. `attributes` are
+  // optional user-supplied attributes associated with the link.
+  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,30 @@
+#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 <unordered_map>
+
+#include "optional.h"
+#include "trace_id.h"
+
+namespace datadog::tracing {
+
+// The map type used for user-supplied span-link attributes.
+using SpanLinkAttributes = std::unordered_map<std::string, std::string>;
+
+struct SpanContext {
+  // 128-bit trace ID of the span.
+  TraceID trace_id;
+  // ID of the span within its trace.
+  std::uint64_t span_id = 0;
+  // W3C `tracestate` header value, if any.
+  Optional<std::string> tracestate;
+  // W3C trace flags, if any.
+  Optional<std::uint32_t> flags;
+};
+
+}  // namespace datadog::tracing

include/datadog/trace_segment.h

@@ -29,6 +29,7 @@
 #include <cstddef>
 #include <memory>
 #include <mutex>
+#include <string>
 #include <utility>
 #include <vector>
 
@@ -108,6 +109,15 @@ 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<std::pair<std::string, std::uint32_t>> 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,31 @@ void Span::set_source(Source source) {
                                             to_tag(source));
 }
 
+SpanContext Span::context() const {
+  SpanContext context;
+  context.trace_id = trace_id();
+  context.span_id = id();
+
+  if (auto 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) {
+  SpanLink link;
+  link.trace_id = context.trace_id;
+  link.span_id = context.span_id;
+  link.tracestate = context.tracestate;
+  link.flags = context.flags;
+  link.attributes = attributes;
+
+  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

@@ -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;

src/datadog/span_link.cpp

@@ -0,0 +1,73 @@
+#include "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>{};
+           }},
+          {true, "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