[API] Add a new AddLink() operation to Span

CHANGELOG.md

@@ -21,6 +21,8 @@ Increment the:
   [#2378](https://github.com/open-telemetry/opentelemetry-cpp/pull/2378)
 * [API] Add InstrumentationScope attributes in TracerProvider::GetTracer()
   [#2371](https://github.com/open-telemetry/opentelemetry-cpp/pull/2371)
+* [API] Add a new AddLink() operation to Span
+  [#2380](https://github.com/open-telemetry/opentelemetry-cpp/pull/2380)
 
 Important changes:
 
@@ -32,6 +34,15 @@ Important changes:
   * When building with `CMake` option `WITH_ABI_VERSION_1=ON` (by default)
     the `ABI` is unchanged, and the fix is not available.
 
+* [API] Add a new AddLink() operation to Span
+  [#2380](https://github.com/open-telemetry/opentelemetry-cpp/pull/2380)
+  * New `API` Span::AddLink() adds a single link to a span.
+  * New `API` Span::AddLinks() adds multiple links to a span.
+  * Because this is an `ABI` breaking change, the fix is only available
+    with the `CMake` option `WITH_ABI_VERSION_2=ON`.
+  * When building with `CMake` option `WITH_ABI_VERSION_1=ON` (by default)
+    the `ABI` is unchanged, and the fix is not available.
+
 * [BUILD] Make WITH_OTLP_HTTP_SSL_PREVIEW mainstream
   [#2378](https://github.com/open-telemetry/opentelemetry-cpp/pull/2378)
   * The experimental `CMake` option `WITH_OTLP_HTTP_SSL_PREVIEW`

api/include/opentelemetry/plugin/tracer.h

@@ -7,6 +7,7 @@
 
 #include "opentelemetry/common/key_value_iterable.h"
 #include "opentelemetry/plugin/detail/tracer_handle.h"
+#include "opentelemetry/trace/span_context_kv_iterable.h"
 #include "opentelemetry/trace/tracer.h"
 #include "opentelemetry/version.h"
 
@@ -49,6 +50,19 @@ class Span final : public trace::Span
     span_->AddEvent(name, timestamp, attributes);
   }
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  void AddLink(const trace::SpanContext &target,
+               const common::KeyValueIterable &attrs) noexcept override
+  {
+    span_->AddLink(target, attrs);
+  }
+
+  void AddLinks(const trace::SpanContextKeyValueIterable &links) noexcept override
+  {
+    span_->AddLinks(links);
+  }
+#endif
+
   void SetStatus(trace::StatusCode code, nostd::string_view description) noexcept override
   {
     span_->SetStatus(code, description);

api/include/opentelemetry/trace/default_span.h

@@ -47,6 +47,14 @@ class DefaultSpan : public Span
                 const common::KeyValueIterable & /* attributes */) noexcept override
   {}
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  void AddLink(const SpanContext & /* target */,
+               const common::KeyValueIterable & /* attrs */) noexcept override
+  {}
+
+  void AddLinks(const SpanContextKeyValueIterable & /* links */) noexcept override {}
+#endif
+
   void SetStatus(StatusCode /* status */, nostd::string_view /* description */) noexcept override {}
 
   void UpdateName(nostd::string_view /* name */) noexcept override {}

api/include/opentelemetry/trace/noop.h

@@ -15,6 +15,7 @@
 #include "opentelemetry/nostd/unique_ptr.h"
 #include "opentelemetry/trace/span.h"
 #include "opentelemetry/trace/span_context.h"
+#include "opentelemetry/trace/span_context_kv_iterable.h"
 #include "opentelemetry/trace/tracer.h"
 #include "opentelemetry/trace/tracer_provider.h"
 #include "opentelemetry/version.h"
@@ -58,6 +59,14 @@ class OPENTELEMETRY_EXPORT NoopSpan final : public Span
                 const common::KeyValueIterable & /*attributes*/) noexcept override
   {}
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  void AddLink(const SpanContext & /* target */,
+               const common::KeyValueIterable & /* attrs */) noexcept override
+  {}
+
+  void AddLinks(const SpanContextKeyValueIterable & /* links */) noexcept override {}
+#endif
+
   void SetStatus(StatusCode /*code*/, nostd::string_view /*description*/) noexcept override {}
 
   void UpdateName(nostd::string_view /*name*/) noexcept override {}

api/include/opentelemetry/trace/span.h

@@ -12,6 +12,8 @@
 #include "opentelemetry/nostd/type_traits.h"
 #include "opentelemetry/trace/canonical_code.h"
 #include "opentelemetry/trace/span_context.h"
+#include "opentelemetry/trace/span_context_kv_iterable.h"
+#include "opentelemetry/trace/span_context_kv_iterable_view.h"
 #include "opentelemetry/trace/span_metadata.h"
 
 #include "opentelemetry/version.h"
@@ -99,6 +101,94 @@ class Span
                        attributes.begin(), attributes.end()});
   }
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+
+  /**
+   * Add link (ABI).
+   *
+   * @since ABI_VERSION 2
+   */
+  virtual void AddLink(const SpanContext &target,
+                       const common::KeyValueIterable &attrs) noexcept = 0;
+
+  /**
+   * Add links (ABI).
+   *
+   * @since ABI_VERSION 2
+   */
+  virtual void AddLinks(const SpanContextKeyValueIterable &links) noexcept = 0;
+
+  /**
+   * Add link (API helper).
+   *
+   * @since ABI_VERSION 2
+   */
+  template <class U,
+            nostd::enable_if_t<common::detail::is_key_value_iterable<U>::value> * = nullptr>
+  void AddLink(const SpanContext &target, const U &attrs)
+  {
+    common::KeyValueIterableView<U> view(attrs);
+    this->AddLink(target, view);
+  }
+
+  /**
+   * Add link (API helper).
+   *
+   * @since ABI_VERSION 2
+   */
+  void AddLink(const SpanContext &target,
+               std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>> attrs)
+  {
+    /* Build a container from std::initializer_list. */
+    nostd::span<const std::pair<nostd::string_view, common::AttributeValue>> container{
+        attrs.begin(), attrs.end()};
+
+    /* Build a view on the container. */
+    common::KeyValueIterableView<
+        nostd::span<const std::pair<nostd::string_view, common::AttributeValue>>>
+        view(container);
+
+    return this->AddLink(target, view);
+  }
+
+  /**
+   * Add links (API helper).
+   *
+   * @since ABI_VERSION 2
+   */
+  template <class U, nostd::enable_if_t<detail::is_span_context_kv_iterable<U>::value> * = nullptr>
+  void AddLinks(const U &links)
+  {
+    SpanContextKeyValueIterableView<U> view(links);
+    this->AddLinks(view);
+  }
+
+  /**
+   * Add links (API helper).
+   *
+   * @since ABI_VERSION 2
+   */
+  void AddLinks(
+      std::initializer_list<
+          std::pair<SpanContext,
+                    std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>>>>
+          links)
+  {
+    /* Build a container from std::initializer_list. */
+    nostd::span<const std::pair<
+        SpanContext, std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>>>>
+        container{links.begin(), links.end()};
+
+    /* Build a view on the container. */
+    SpanContextKeyValueIterableView<nostd::span<const std::pair<
+        SpanContext, std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>>>>>
+        view(container);
+
+    return this->AddLinks(view);
+  }
+
+#endif /* OPENTELEMETRY_ABI_VERSION_NO */
+
   // Sets the status of the span. The default status is Unset. Only the value of
   // the last call will be
   // recorded, and implementations are free to ignore previous calls.

api/include/opentelemetry/trace/span_context_kv_iterable.h

@@ -6,6 +6,7 @@
 #include "opentelemetry/common/attribute_value.h"
 #include "opentelemetry/common/key_value_iterable_view.h"
 #include "opentelemetry/nostd/function_ref.h"
+#include "opentelemetry/trace/span_context.h"
 #include "opentelemetry/version.h"
 
 OPENTELEMETRY_BEGIN_NAMESPACE

examples/plugin/plugin/tracer.cc

@@ -49,6 +49,14 @@ class Span final : public trace::Span
                 const common::KeyValueIterable & /*attributes*/) noexcept override
   {}
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  void AddLink(const trace::SpanContext & /* target */,
+               const common::KeyValueIterable & /* attrs */) noexcept override
+  {}
+
+  void AddLinks(const trace::SpanContextKeyValueIterable & /* links */) noexcept override {}
+#endif
+
   void SetStatus(trace::StatusCode /*code*/, nostd::string_view /*description*/) noexcept override
   {}
 

sdk/src/trace/span.cc

@@ -146,6 +146,35 @@ void Span::AddEvent(nostd::string_view name,
   recordable_->AddEvent(name, timestamp, attributes);
 }
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+void Span::AddLink(const opentelemetry::trace::SpanContext &target,
+                   const opentelemetry::common::KeyValueIterable &attrs) noexcept
+{
+  std::lock_guard<std::mutex> lock_guard{mu_};
+  if (recordable_ == nullptr)
+  {
+    return;
+  }
+
+  recordable_->AddLink(target, attrs);
+}
+
+void Span::AddLinks(const opentelemetry::trace::SpanContextKeyValueIterable &links) noexcept
+{
+  std::lock_guard<std::mutex> lock_guard{mu_};
+  if (recordable_ == nullptr)
+  {
+    return;
+  }
+
+  links.ForEachKeyValue([&](opentelemetry::trace::SpanContext span_context,
+                            const common::KeyValueIterable &attributes) {
+    recordable_->AddLink(span_context, attributes);
+    return true;
+  });
+}
+#endif
+
 void Span::SetStatus(opentelemetry::trace::StatusCode code, nostd::string_view description) noexcept
 {
   std::lock_guard<std::mutex> lock_guard{mu_};

sdk/src/trace/span.h

@@ -45,6 +45,13 @@ class Span final : public opentelemetry::trace::Span
   void SetStatus(opentelemetry::trace::StatusCode code,
                  nostd::string_view description) noexcept override;
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  void AddLink(const opentelemetry::trace::SpanContext &target,
+               const opentelemetry::common::KeyValueIterable &attrs) noexcept override;
+
+  void AddLinks(const opentelemetry::trace::SpanContextKeyValueIterable &links) noexcept override;
+#endif
+
   void UpdateName(nostd::string_view name) noexcept override;
 
   void End(const opentelemetry::trace::EndSpanOptions &options = {}) noexcept override;