From b4ba4aaad380799b58f678308edeff75d98fb23b Mon Sep 17 00:00:00 2001
From: Marc Alff <marc.alff@oracle.com>
Date: Fri, 20 Oct 2023 01:34:27 +0200
Subject: [PATCH 1/8] Fixes #2361

---
 api/include/opentelemetry/plugin/tracer.h     |  8 +++
 .../opentelemetry/trace/default_span.h        |  4 ++
 api/include/opentelemetry/trace/noop.h        |  5 ++
 api/include/opentelemetry/trace/span.h        | 49 +++++++++++++++++++
 .../trace/span_context_kv_iterable.h          |  1 +
 examples/plugin/plugin/tracer.cc              |  4 ++
 sdk/src/trace/span.cc                         | 17 +++++++
 sdk/src/trace/span.h                          |  4 ++
 8 files changed, 92 insertions(+)

diff --git a/api/include/opentelemetry/plugin/tracer.h b/api/include/opentelemetry/plugin/tracer.h
index b87f9e889f..6ca2228f29 100644
--- a/api/include/opentelemetry/plugin/tracer.h
+++ b/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,13 @@ class Span final : public trace::Span
     span_->AddEvent(name, timestamp, attributes);
   }
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  void AddLink(const trace::SpanContextKeyValueIterable *links) noexcept override
+  {
+    span_->AddLink(links);
+  }
+#endif
+
   void SetStatus(trace::StatusCode code, nostd::string_view description) noexcept override
   {
     span_->SetStatus(code, description);
diff --git a/api/include/opentelemetry/trace/default_span.h b/api/include/opentelemetry/trace/default_span.h
index cccc7951ad..036ac309be 100644
--- a/api/include/opentelemetry/trace/default_span.h
+++ b/api/include/opentelemetry/trace/default_span.h
@@ -47,6 +47,10 @@ class DefaultSpan : public Span
                 const common::KeyValueIterable & /* attributes */) noexcept override
   {}
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  void AddLink(const SpanContextKeyValueIterable *links) noexcept override {}
+#endif
+
   void SetStatus(StatusCode /* status */, nostd::string_view /* description */) noexcept override {}
 
   void UpdateName(nostd::string_view /* name */) noexcept override {}
diff --git a/api/include/opentelemetry/trace/noop.h b/api/include/opentelemetry/trace/noop.h
index c6a5838867..ca467298cf 100644
--- a/api/include/opentelemetry/trace/noop.h
+++ b/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,10 @@ class OPENTELEMETRY_EXPORT NoopSpan final : public Span
                 const common::KeyValueIterable & /*attributes*/) noexcept override
   {}
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  void AddLink(const SpanContextKeyValueIterable * /* links */) noexcept override {}
+#endif
+
   void SetStatus(StatusCode /*code*/, nostd::string_view /*description*/) noexcept override {}
 
   void UpdateName(nostd::string_view /*name*/) noexcept override {}
diff --git a/api/include/opentelemetry/trace/span.h b/api/include/opentelemetry/trace/span.h
index ffd145a30d..7a7734dcdb 100644
--- a/api/include/opentelemetry/trace/span.h
+++ b/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,53 @@ class Span
                        attributes.begin(), attributes.end()});
   }
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+
+  /**
+   * Add links (ABI).
+   *
+   * @since ABI_VERSION 2
+   */
+  virtual void AddLink(const SpanContextKeyValueIterable *links) noexcept = 0;
+
+  /**
+   * 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 AddLink(const U &links)
+  {
+    SpanContextKeyValueIterableView<U> view(links);
+    this->AddLink(&view);
+  }
+
+  /**
+   * Add links (API helper).
+   *
+   * @since ABI_VERSION 2
+   */
+  void AddLink(
+      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>>>>
+        links_span{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(links_span);
+
+    return this->AddLink(&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.
diff --git a/api/include/opentelemetry/trace/span_context_kv_iterable.h b/api/include/opentelemetry/trace/span_context_kv_iterable.h
index 8f3010ce9d..aed3474272 100644
--- a/api/include/opentelemetry/trace/span_context_kv_iterable.h
+++ b/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
diff --git a/examples/plugin/plugin/tracer.cc b/examples/plugin/plugin/tracer.cc
index 55de64438d..e24056c117 100644
--- a/examples/plugin/plugin/tracer.cc
+++ b/examples/plugin/plugin/tracer.cc
@@ -49,6 +49,10 @@ class Span final : public trace::Span
                 const common::KeyValueIterable & /*attributes*/) noexcept override
   {}
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  void AddLink(const trace::SpanContextKeyValueIterable * /* links */) noexcept override {}
+#endif
+
   void SetStatus(trace::StatusCode /*code*/, nostd::string_view /*description*/) noexcept override
   {}
 
diff --git a/sdk/src/trace/span.cc b/sdk/src/trace/span.cc
index c7524d43aa..eef67e82d6 100644
--- a/sdk/src/trace/span.cc
+++ b/sdk/src/trace/span.cc
@@ -146,6 +146,23 @@ void Span::AddEvent(nostd::string_view name,
   recordable_->AddEvent(name, timestamp, attributes);
 }
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+void Span::AddLink(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_};
diff --git a/sdk/src/trace/span.h b/sdk/src/trace/span.h
index 75e31e9500..c49b204443 100644
--- a/sdk/src/trace/span.h
+++ b/sdk/src/trace/span.h
@@ -45,6 +45,10 @@ 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::SpanContextKeyValueIterable *links) noexcept override;
+#endif
+
   void UpdateName(nostd::string_view name) noexcept override;
 
   void End(const opentelemetry::trace::EndSpanOptions &options = {}) noexcept override;

From a2c66b8cc593f6d17641af804ad5bb15ff7731b5 Mon Sep 17 00:00:00 2001
From: Marc Alff <marc.alff@oracle.com>
Date: Fri, 20 Oct 2023 09:07:10 +0200
Subject: [PATCH 2/8] Fixed build warning

---
 api/include/opentelemetry/trace/default_span.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api/include/opentelemetry/trace/default_span.h b/api/include/opentelemetry/trace/default_span.h
index 036ac309be..86d43ea5e1 100644
--- a/api/include/opentelemetry/trace/default_span.h
+++ b/api/include/opentelemetry/trace/default_span.h
@@ -48,7 +48,7 @@ class DefaultSpan : public Span
   {}
 
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
-  void AddLink(const SpanContextKeyValueIterable *links) noexcept override {}
+  void AddLink(const SpanContextKeyValueIterable * /* links */) noexcept override {}
 #endif
 
   void SetStatus(StatusCode /* status */, nostd::string_view /* description */) noexcept override {}

From 76ce23b42bd3f36c54b0db16cac626ee5e64db04 Mon Sep 17 00:00:00 2001
From: Marc Alff <marc.alff@oracle.com>
Date: Sun, 22 Oct 2023 21:34:59 +0200
Subject: [PATCH 3/8] Added unit tests.

---
 CHANGELOG.md                  |  10 ++
 sdk/test/trace/tracer_test.cc | 232 ++++++++++++++++++++++++++++++++++
 2 files changed, 242 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 01f54cf339..2043b0f472 100644
--- a/CHANGELOG.md
+++ b/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,14 @@ 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 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`
diff --git a/sdk/test/trace/tracer_test.cc b/sdk/test/trace/tracer_test.cc
index 45b5fc010f..5013598b5b 100644
--- a/sdk/test/trace/tracer_test.cc
+++ b/sdk/test/trace/tracer_test.cc
@@ -519,6 +519,238 @@ TEST(Tracer, SpanSetLinks)
   }
 }
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+TEST(Tracer, SpanAddLinksAbiv2)
+{
+  InMemorySpanExporter *exporter              = new InMemorySpanExporter();
+  std::shared_ptr<InMemorySpanData> span_data = exporter->GetData();
+  auto tracer                                 = initTracer(std::unique_ptr<SpanExporter>{exporter});
+
+  {
+    auto span = tracer->StartSpan("span 1");
+    // Single span link passed through Initialization list
+    span->AddLink({{SpanContext(false, false), {{"attr2", 2}}}});
+    span->End();
+
+    auto spans = span_data->GetSpans();
+    ASSERT_EQ(1, spans.size());
+
+    auto &span_data_links = spans.at(0)->GetLinks();
+    ASSERT_EQ(1, span_data_links.size());
+    auto link = span_data_links.at(0);
+    ASSERT_EQ(nostd::get<int>(link.GetAttributes().at("attr2")), 2);
+  }
+
+  {
+    auto span = tracer->StartSpan("span 2");
+    // Multiple span links passed through Initialization list
+    span->AddLink(
+        {{SpanContext(false, false), {{"attr2", 2}}}, {SpanContext(false, false), {{"attr3", 3}}}});
+    span->End();
+
+    auto spans = span_data->GetSpans();
+    ASSERT_EQ(1, spans.size());
+
+    auto &span_data_links = spans.at(0)->GetLinks();
+    ASSERT_EQ(2, span_data_links.size());
+    auto link1 = span_data_links.at(0);
+    ASSERT_EQ(nostd::get<int>(link1.GetAttributes().at("attr2")), 2);
+    auto link2 = span_data_links.at(1);
+    ASSERT_EQ(nostd::get<int>(link2.GetAttributes().at("attr3")), 3);
+  }
+
+  {
+    auto span = tracer->StartSpan("span 3");
+    // Multiple links, each with multiple attributes passed through Initialization list
+    span->AddLink({{SpanContext(false, false), {{"attr2", 2}, {"attr3", 3}}},
+                   {SpanContext(false, false), {{"attr4", 4}}}});
+    span->End();
+
+    auto spans = span_data->GetSpans();
+    ASSERT_EQ(1, spans.size());
+
+    auto &span_data_links = spans.at(0)->GetLinks();
+    ASSERT_EQ(2, span_data_links.size());
+    auto link1 = span_data_links.at(0);
+    ASSERT_EQ(nostd::get<int>(link1.GetAttributes().at("attr2")), 2);
+    ASSERT_EQ(nostd::get<int>(link1.GetAttributes().at("attr3")), 3);
+    auto link2 = span_data_links.at(1);
+    ASSERT_EQ(nostd::get<int>(link2.GetAttributes().at("attr4")), 4);
+  }
+
+  {
+    std::map<std::string, std::string> attrs1 = {{"attr1", "1"}, {"attr2", "2"}};
+    std::map<std::string, std::string> attrs2 = {{"attr3", "3"}, {"attr4", "4"}};
+
+    std::vector<std::pair<SpanContext, std::map<std::string, std::string>>> links = {
+        {SpanContext(false, false), attrs1}, {SpanContext(false, false), attrs2}};
+
+    auto span = tracer->StartSpan("span 4");
+    span->AddLink(links);
+    span->End();
+
+    auto spans = span_data->GetSpans();
+
+    auto &span_data_links = spans.at(0)->GetLinks();
+    ASSERT_EQ(2, span_data_links.size());
+    auto link1 = span_data_links.at(0);
+    ASSERT_EQ(nostd::get<std::string>(link1.GetAttributes().at("attr1")), "1");
+    ASSERT_EQ(nostd::get<std::string>(link1.GetAttributes().at("attr2")), "2");
+    auto link2 = span_data_links.at(1);
+    ASSERT_EQ(nostd::get<std::string>(link2.GetAttributes().at("attr3")), "3");
+    ASSERT_EQ(nostd::get<std::string>(link2.GetAttributes().at("attr4")), "4");
+  }
+
+  {
+    auto span = tracer->StartSpan("span 5");
+
+    // Single span link passed through Initialization list
+    span->AddLink({{SpanContext(false, false), {{"attr10", 10}}}});
+    span->AddLink({{SpanContext(false, false), {{"attr11", 11}}}});
+
+    // Multiple span links passed through Initialization list
+    span->AddLink({{SpanContext(false, false), {{"attr12", 12}}},
+                   {SpanContext(false, false), {{"attr13", 13}}}});
+    span->AddLink({{SpanContext(false, false), {{"attr14", 14}}},
+                   {SpanContext(false, false), {{"attr15", 15}}}});
+
+    // Multiple links, each with multiple attributes passed through Initialization list
+    span->AddLink({{SpanContext(false, false), {{"attr16", 16}, {"attr17", 17}}},
+                   {SpanContext(false, false), {{"attr18", 18}}}});
+    span->AddLink({{SpanContext(false, false), {{"attr19", 19}, {"attr20", 20}}},
+                   {SpanContext(false, false), {{"attr21", 21}}}});
+
+    std::map<std::string, std::string> attrsa1 = {{"attra1", "1"}, {"attra2", "2"}};
+    std::map<std::string, std::string> attrsa2 = {{"attra3", "3"}, {"attra4", "4"}};
+
+    std::vector<std::pair<SpanContext, std::map<std::string, std::string>>> linksa = {
+        {SpanContext(false, false), attrsa1}, {SpanContext(false, false), attrsa2}};
+
+    span->AddLink(linksa);
+
+    std::map<std::string, std::string> attrsb1 = {{"attrb1", "1"}, {"attrb2", "2"}};
+    std::map<std::string, std::string> attrsb2 = {{"attrb3", "3"}, {"attrb4", "4"}};
+
+    std::vector<std::pair<SpanContext, std::map<std::string, std::string>>> linksb = {
+        {SpanContext(false, false), attrsb1}, {SpanContext(false, false), attrsb2}};
+
+    span->AddLink(linksb);
+
+    span->End();
+
+    auto spans = span_data->GetSpans();
+    ASSERT_EQ(1, spans.size());
+
+    auto &span_data_links = spans.at(0)->GetLinks();
+    ASSERT_EQ(14, span_data_links.size());
+
+    {
+      auto link = span_data_links.at(0);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 1);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr10")), 10);
+    }
+
+    {
+      auto link = span_data_links.at(1);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 1);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr11")), 11);
+    }
+
+    {
+      auto link = span_data_links.at(2);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 1);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr12")), 12);
+    }
+
+    {
+      auto link = span_data_links.at(3);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 1);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr13")), 13);
+    }
+
+    {
+      auto link = span_data_links.at(4);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 1);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr14")), 14);
+    }
+
+    {
+      auto link = span_data_links.at(5);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 1);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr15")), 15);
+    }
+
+    {
+      auto link = span_data_links.at(6);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 2);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr16")), 16);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr17")), 17);
+    }
+
+    {
+      auto link = span_data_links.at(7);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 1);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr18")), 18);
+    }
+
+    {
+      auto link = span_data_links.at(8);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 2);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr19")), 19);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr20")), 20);
+    }
+
+    {
+      auto link = span_data_links.at(9);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 1);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr21")), 21);
+    }
+
+    {
+      auto link = span_data_links.at(10);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 2);
+      ASSERT_EQ(nostd::get<std::string>(attrs.at("attra1")), "1");
+      ASSERT_EQ(nostd::get<std::string>(attrs.at("attra2")), "2");
+    }
+
+    {
+      auto link = span_data_links.at(11);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 2);
+      ASSERT_EQ(nostd::get<std::string>(attrs.at("attra3")), "3");
+      ASSERT_EQ(nostd::get<std::string>(attrs.at("attra4")), "4");
+    }
+
+    {
+      auto link = span_data_links.at(12);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 2);
+      ASSERT_EQ(nostd::get<std::string>(attrs.at("attrb1")), "1");
+      ASSERT_EQ(nostd::get<std::string>(attrs.at("attrb2")), "2");
+    }
+
+    {
+      auto link = span_data_links.at(13);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 2);
+      ASSERT_EQ(nostd::get<std::string>(attrs.at("attrb3")), "3");
+      ASSERT_EQ(nostd::get<std::string>(attrs.at("attrb4")), "4");
+    }
+  }
+}
+#endif /* OPENTELEMETRY_ABI_VERSION_NO >= 2 */
+
 TEST(Tracer, TestAlwaysOnSampler)
 {
   InMemorySpanExporter *exporter              = new InMemorySpanExporter();

From 53566001bb73ac8069acd2b76559d2734a0b7ce4 Mon Sep 17 00:00:00 2001
From: Marc Alff <marc.alff@oracle.com>
Date: Sun, 22 Oct 2023 23:24:05 +0200
Subject: [PATCH 4/8] Add single link

---
 CHANGELOG.md                                  |   3 +-
 api/include/opentelemetry/plugin/tracer.h     |  10 +-
 .../opentelemetry/trace/default_span.h        |   5 +-
 api/include/opentelemetry/trace/noop.h        |   6 +-
 api/include/opentelemetry/trace/span.h        |  55 ++++-
 examples/plugin/plugin/tracer.cc              |   6 +-
 sdk/src/trace/span.cc                         |  18 +-
 sdk/src/trace/span.h                          |   5 +-
 sdk/test/trace/tracer_test.cc                 | 230 +++++++++++++++---
 9 files changed, 285 insertions(+), 53 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2043b0f472..ddc222bf3b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,7 +36,8 @@ Important changes:
 
 * [API] Add a new AddLink() operation to Span
   [#2380](https://github.com/open-telemetry/opentelemetry-cpp/pull/2380)
-  * new `API` Span::AddLink() adds links to a span.
+  * 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)
diff --git a/api/include/opentelemetry/plugin/tracer.h b/api/include/opentelemetry/plugin/tracer.h
index 6ca2228f29..068b08071d 100644
--- a/api/include/opentelemetry/plugin/tracer.h
+++ b/api/include/opentelemetry/plugin/tracer.h
@@ -51,9 +51,15 @@ class Span final : public trace::Span
   }
 
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
-  void AddLink(const trace::SpanContextKeyValueIterable *links) noexcept override
+  void AddLink(const trace::SpanContext &target,
+               const common::KeyValueIterable &attrs) noexcept override
   {
-    span_->AddLink(links);
+    span_->AddLink(target, attrs);
+  }
+
+  void AddLinks(const trace::SpanContextKeyValueIterable &links) noexcept override
+  {
+    span_->AddLinks(links);
   }
 #endif
 
diff --git a/api/include/opentelemetry/trace/default_span.h b/api/include/opentelemetry/trace/default_span.h
index 86d43ea5e1..3d0088de0d 100644
--- a/api/include/opentelemetry/trace/default_span.h
+++ b/api/include/opentelemetry/trace/default_span.h
@@ -48,7 +48,10 @@ class DefaultSpan : public Span
   {}
 
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
-  void AddLink(const SpanContextKeyValueIterable * /* links */) noexcept override {}
+  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 {}
diff --git a/api/include/opentelemetry/trace/noop.h b/api/include/opentelemetry/trace/noop.h
index ca467298cf..407f3c1ac9 100644
--- a/api/include/opentelemetry/trace/noop.h
+++ b/api/include/opentelemetry/trace/noop.h
@@ -60,7 +60,11 @@ class OPENTELEMETRY_EXPORT NoopSpan final : public Span
   {}
 
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
-  void AddLink(const SpanContextKeyValueIterable * /* links */) noexcept override {}
+  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 {}
diff --git a/api/include/opentelemetry/trace/span.h b/api/include/opentelemetry/trace/span.h
index 7a7734dcdb..e7e9a679be 100644
--- a/api/include/opentelemetry/trace/span.h
+++ b/api/include/opentelemetry/trace/span.h
@@ -103,12 +103,53 @@ class Span
 
 #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 AddLink(const SpanContextKeyValueIterable *links) noexcept = 0;
+  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).
@@ -116,10 +157,10 @@ class Span
    * @since ABI_VERSION 2
    */
   template <class U, nostd::enable_if_t<detail::is_span_context_kv_iterable<U>::value> * = nullptr>
-  void AddLink(const U &links)
+  void AddLinks(const U &links)
   {
     SpanContextKeyValueIterableView<U> view(links);
-    this->AddLink(&view);
+    this->AddLinks(view);
   }
 
   /**
@@ -127,7 +168,7 @@ class Span
    *
    * @since ABI_VERSION 2
    */
-  void AddLink(
+  void AddLinks(
       std::initializer_list<
           std::pair<SpanContext,
                     std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>>>>
@@ -136,14 +177,14 @@ class Span
     /* Build a container from std::initializer_list. */
     nostd::span<const std::pair<
         SpanContext, std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>>>>
-        links_span{links.begin(), links.end()};
+        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(links_span);
+        view(container);
 
-    return this->AddLink(&view);
+    return this->AddLinks(view);
   }
 
 #endif /* OPENTELEMETRY_ABI_VERSION_NO */
diff --git a/examples/plugin/plugin/tracer.cc b/examples/plugin/plugin/tracer.cc
index e24056c117..9579d0204e 100644
--- a/examples/plugin/plugin/tracer.cc
+++ b/examples/plugin/plugin/tracer.cc
@@ -50,7 +50,11 @@ class Span final : public trace::Span
   {}
 
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
-  void AddLink(const trace::SpanContextKeyValueIterable * /* links */) noexcept override {}
+  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
diff --git a/sdk/src/trace/span.cc b/sdk/src/trace/span.cc
index eef67e82d6..25708cddd9 100644
--- a/sdk/src/trace/span.cc
+++ b/sdk/src/trace/span.cc
@@ -147,7 +147,8 @@ void Span::AddEvent(nostd::string_view name,
 }
 
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
-void Span::AddLink(const opentelemetry::trace::SpanContextKeyValueIterable *links) noexcept
+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)
@@ -155,8 +156,19 @@ void Span::AddLink(const opentelemetry::trace::SpanContextKeyValueIterable *link
     return;
   }
 
-  links->ForEachKeyValue([&](opentelemetry::trace::SpanContext span_context,
-                             const common::KeyValueIterable &attributes) {
+  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;
   });
diff --git a/sdk/src/trace/span.h b/sdk/src/trace/span.h
index c49b204443..bd255b86b6 100644
--- a/sdk/src/trace/span.h
+++ b/sdk/src/trace/span.h
@@ -46,7 +46,10 @@ class Span final : public opentelemetry::trace::Span
                  nostd::string_view description) noexcept override;
 
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
-  void AddLink(const opentelemetry::trace::SpanContextKeyValueIterable *links) noexcept override;
+  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;
diff --git a/sdk/test/trace/tracer_test.cc b/sdk/test/trace/tracer_test.cc
index 5013598b5b..2dd9ace86b 100644
--- a/sdk/test/trace/tracer_test.cc
+++ b/sdk/test/trace/tracer_test.cc
@@ -519,6 +519,113 @@ TEST(Tracer, SpanSetLinks)
   }
 }
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+TEST(Tracer, SpanAddLinkAbiv2)
+{
+  InMemorySpanExporter *exporter              = new InMemorySpanExporter();
+  std::shared_ptr<InMemorySpanData> span_data = exporter->GetData();
+  auto tracer                                 = initTracer(std::unique_ptr<SpanExporter>{exporter});
+
+  {
+    auto span = tracer->StartSpan("span");
+    SpanContext target(false, false);
+    // Single link attribute passed through Initialization list
+    span->AddLink(target, {{"attr2", 2}});
+    span->End();
+
+    auto spans = span_data->GetSpans();
+    ASSERT_EQ(1, spans.size());
+
+    auto &span_data_links = spans.at(0)->GetLinks();
+    ASSERT_EQ(1, span_data_links.size());
+    auto link  = span_data_links.at(0);
+    auto attrs = link.GetAttributes();
+    ASSERT_EQ(nostd::get<int>(attrs.at("attr2")), 2);
+  }
+
+  {
+    auto span = tracer->StartSpan("span");
+    SpanContext target(false, false);
+    // Multiple link attributes passed through Initialization list
+    span->AddLink(target, {{"attr2", 2}, {"attr3", 3}});
+    span->End();
+
+    auto spans = span_data->GetSpans();
+    ASSERT_EQ(1, spans.size());
+
+    auto &span_data_links = spans.at(0)->GetLinks();
+    ASSERT_EQ(1, span_data_links.size());
+    auto link  = span_data_links.at(0);
+    auto attrs = link.GetAttributes();
+    ASSERT_EQ(nostd::get<int>(attrs.at("attr2")), 2);
+    ASSERT_EQ(nostd::get<int>(attrs.at("attr3")), 3);
+  }
+
+  {
+    std::map<std::string, std::string> attrs_map = {{"attr1", "1"}, {"attr2", "2"}};
+
+    auto span = tracer->StartSpan("span");
+    SpanContext target(false, false);
+    span->AddLink(target, attrs_map);
+    span->End();
+
+    auto spans = span_data->GetSpans();
+
+    auto &span_data_links = spans.at(0)->GetLinks();
+    ASSERT_EQ(1, span_data_links.size());
+    auto link  = span_data_links.at(0);
+    auto attrs = link.GetAttributes();
+    ASSERT_EQ(nostd::get<std::string>(attrs.at("attr1")), "1");
+    ASSERT_EQ(nostd::get<std::string>(attrs.at("attr2")), "2");
+  }
+
+  {
+    auto span = tracer->StartSpan("span");
+    SpanContext target(false, false);
+
+    // Single link attribute passed through Initialization list
+    span->AddLink(target, {{"attr1", 1}});
+
+    // Multiple link attributes passed through Initialization list
+    span->AddLink(target, {{"attr2", 2}, {"attr3", 3}});
+
+    std::map<std::string, std::string> attrs_map = {{"attr4", "4"}, {"attr5", "5"}};
+    span->AddLink(target, attrs_map);
+
+    span->End();
+
+    auto spans = span_data->GetSpans();
+    ASSERT_EQ(1, spans.size());
+
+    auto &span_data_links = spans.at(0)->GetLinks();
+    ASSERT_EQ(3, span_data_links.size());
+
+    {
+      auto link  = span_data_links.at(0);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 1);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr1")), 1);
+    }
+
+    {
+      auto link  = span_data_links.at(1);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 2);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr2")), 2);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr3")), 3);
+    }
+
+    {
+      auto link  = span_data_links.at(2);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 2);
+      ASSERT_EQ(nostd::get<std::string>(attrs.at("attr4")), "4");
+      ASSERT_EQ(nostd::get<std::string>(attrs.at("attr5")), "5");
+    }
+  }
+}
+#endif /* OPENTELEMETRY_ABI_VERSION_NO >= 2 */
+
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
 TEST(Tracer, SpanAddLinksAbiv2)
 {
@@ -527,9 +634,9 @@ TEST(Tracer, SpanAddLinksAbiv2)
   auto tracer                                 = initTracer(std::unique_ptr<SpanExporter>{exporter});
 
   {
-    auto span = tracer->StartSpan("span 1");
+    auto span = tracer->StartSpan("span");
     // Single span link passed through Initialization list
-    span->AddLink({{SpanContext(false, false), {{"attr2", 2}}}});
+    span->AddLinks({{SpanContext(false, false), {{"attr2", 2}}}});
     span->End();
 
     auto spans = span_data->GetSpans();
@@ -542,9 +649,9 @@ TEST(Tracer, SpanAddLinksAbiv2)
   }
 
   {
-    auto span = tracer->StartSpan("span 2");
+    auto span = tracer->StartSpan("span");
     // Multiple span links passed through Initialization list
-    span->AddLink(
+    span->AddLinks(
         {{SpanContext(false, false), {{"attr2", 2}}}, {SpanContext(false, false), {{"attr3", 3}}}});
     span->End();
 
@@ -560,10 +667,10 @@ TEST(Tracer, SpanAddLinksAbiv2)
   }
 
   {
-    auto span = tracer->StartSpan("span 3");
+    auto span = tracer->StartSpan("span");
     // Multiple links, each with multiple attributes passed through Initialization list
-    span->AddLink({{SpanContext(false, false), {{"attr2", 2}, {"attr3", 3}}},
-                   {SpanContext(false, false), {{"attr4", 4}}}});
+    span->AddLinks({{SpanContext(false, false), {{"attr2", 2}, {"attr3", 3}}},
+                    {SpanContext(false, false), {{"attr4", 4}}}});
     span->End();
 
     auto spans = span_data->GetSpans();
@@ -585,8 +692,8 @@ TEST(Tracer, SpanAddLinksAbiv2)
     std::vector<std::pair<SpanContext, std::map<std::string, std::string>>> links = {
         {SpanContext(false, false), attrs1}, {SpanContext(false, false), attrs2}};
 
-    auto span = tracer->StartSpan("span 4");
-    span->AddLink(links);
+    auto span = tracer->StartSpan("span");
+    span->AddLinks(links);
     span->End();
 
     auto spans = span_data->GetSpans();
@@ -602,23 +709,23 @@ TEST(Tracer, SpanAddLinksAbiv2)
   }
 
   {
-    auto span = tracer->StartSpan("span 5");
+    auto span = tracer->StartSpan("span");
 
     // Single span link passed through Initialization list
-    span->AddLink({{SpanContext(false, false), {{"attr10", 10}}}});
-    span->AddLink({{SpanContext(false, false), {{"attr11", 11}}}});
+    span->AddLinks({{SpanContext(false, false), {{"attr10", 10}}}});
+    span->AddLinks({{SpanContext(false, false), {{"attr11", 11}}}});
 
     // Multiple span links passed through Initialization list
-    span->AddLink({{SpanContext(false, false), {{"attr12", 12}}},
-                   {SpanContext(false, false), {{"attr13", 13}}}});
-    span->AddLink({{SpanContext(false, false), {{"attr14", 14}}},
-                   {SpanContext(false, false), {{"attr15", 15}}}});
+    span->AddLinks({{SpanContext(false, false), {{"attr12", 12}}},
+                    {SpanContext(false, false), {{"attr13", 13}}}});
+    span->AddLinks({{SpanContext(false, false), {{"attr14", 14}}},
+                    {SpanContext(false, false), {{"attr15", 15}}}});
 
     // Multiple links, each with multiple attributes passed through Initialization list
-    span->AddLink({{SpanContext(false, false), {{"attr16", 16}, {"attr17", 17}}},
-                   {SpanContext(false, false), {{"attr18", 18}}}});
-    span->AddLink({{SpanContext(false, false), {{"attr19", 19}, {"attr20", 20}}},
-                   {SpanContext(false, false), {{"attr21", 21}}}});
+    span->AddLinks({{SpanContext(false, false), {{"attr16", 16}, {"attr17", 17}}},
+                    {SpanContext(false, false), {{"attr18", 18}}}});
+    span->AddLinks({{SpanContext(false, false), {{"attr19", 19}, {"attr20", 20}}},
+                    {SpanContext(false, false), {{"attr21", 21}}}});
 
     std::map<std::string, std::string> attrsa1 = {{"attra1", "1"}, {"attra2", "2"}};
     std::map<std::string, std::string> attrsa2 = {{"attra3", "3"}, {"attra4", "4"}};
@@ -626,7 +733,7 @@ TEST(Tracer, SpanAddLinksAbiv2)
     std::vector<std::pair<SpanContext, std::map<std::string, std::string>>> linksa = {
         {SpanContext(false, false), attrsa1}, {SpanContext(false, false), attrsa2}};
 
-    span->AddLink(linksa);
+    span->AddLinks(linksa);
 
     std::map<std::string, std::string> attrsb1 = {{"attrb1", "1"}, {"attrb2", "2"}};
     std::map<std::string, std::string> attrsb2 = {{"attrb3", "3"}, {"attrb4", "4"}};
@@ -634,7 +741,7 @@ TEST(Tracer, SpanAddLinksAbiv2)
     std::vector<std::pair<SpanContext, std::map<std::string, std::string>>> linksb = {
         {SpanContext(false, false), attrsb1}, {SpanContext(false, false), attrsb2}};
 
-    span->AddLink(linksb);
+    span->AddLinks(linksb);
 
     span->End();
 
@@ -645,49 +752,49 @@ TEST(Tracer, SpanAddLinksAbiv2)
     ASSERT_EQ(14, span_data_links.size());
 
     {
-      auto link = span_data_links.at(0);
+      auto link  = span_data_links.at(0);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 1);
       ASSERT_EQ(nostd::get<int>(attrs.at("attr10")), 10);
     }
 
     {
-      auto link = span_data_links.at(1);
+      auto link  = span_data_links.at(1);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 1);
       ASSERT_EQ(nostd::get<int>(attrs.at("attr11")), 11);
     }
 
     {
-      auto link = span_data_links.at(2);
+      auto link  = span_data_links.at(2);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 1);
       ASSERT_EQ(nostd::get<int>(attrs.at("attr12")), 12);
     }
 
     {
-      auto link = span_data_links.at(3);
+      auto link  = span_data_links.at(3);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 1);
       ASSERT_EQ(nostd::get<int>(attrs.at("attr13")), 13);
     }
 
     {
-      auto link = span_data_links.at(4);
+      auto link  = span_data_links.at(4);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 1);
       ASSERT_EQ(nostd::get<int>(attrs.at("attr14")), 14);
     }
 
     {
-      auto link = span_data_links.at(5);
+      auto link  = span_data_links.at(5);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 1);
       ASSERT_EQ(nostd::get<int>(attrs.at("attr15")), 15);
     }
 
     {
-      auto link = span_data_links.at(6);
+      auto link  = span_data_links.at(6);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 2);
       ASSERT_EQ(nostd::get<int>(attrs.at("attr16")), 16);
@@ -695,14 +802,14 @@ TEST(Tracer, SpanAddLinksAbiv2)
     }
 
     {
-      auto link = span_data_links.at(7);
+      auto link  = span_data_links.at(7);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 1);
       ASSERT_EQ(nostd::get<int>(attrs.at("attr18")), 18);
     }
 
     {
-      auto link = span_data_links.at(8);
+      auto link  = span_data_links.at(8);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 2);
       ASSERT_EQ(nostd::get<int>(attrs.at("attr19")), 19);
@@ -710,14 +817,14 @@ TEST(Tracer, SpanAddLinksAbiv2)
     }
 
     {
-      auto link = span_data_links.at(9);
+      auto link  = span_data_links.at(9);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 1);
       ASSERT_EQ(nostd::get<int>(attrs.at("attr21")), 21);
     }
 
     {
-      auto link = span_data_links.at(10);
+      auto link  = span_data_links.at(10);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 2);
       ASSERT_EQ(nostd::get<std::string>(attrs.at("attra1")), "1");
@@ -725,7 +832,7 @@ TEST(Tracer, SpanAddLinksAbiv2)
     }
 
     {
-      auto link = span_data_links.at(11);
+      auto link  = span_data_links.at(11);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 2);
       ASSERT_EQ(nostd::get<std::string>(attrs.at("attra3")), "3");
@@ -733,7 +840,7 @@ TEST(Tracer, SpanAddLinksAbiv2)
     }
 
     {
-      auto link = span_data_links.at(12);
+      auto link  = span_data_links.at(12);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 2);
       ASSERT_EQ(nostd::get<std::string>(attrs.at("attrb1")), "1");
@@ -741,7 +848,7 @@ TEST(Tracer, SpanAddLinksAbiv2)
     }
 
     {
-      auto link = span_data_links.at(13);
+      auto link  = span_data_links.at(13);
       auto attrs = link.GetAttributes();
       ASSERT_EQ(attrs.size(), 2);
       ASSERT_EQ(nostd::get<std::string>(attrs.at("attrb3")), "3");
@@ -751,6 +858,57 @@ TEST(Tracer, SpanAddLinksAbiv2)
 }
 #endif /* OPENTELEMETRY_ABI_VERSION_NO >= 2 */
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+TEST(Tracer, SpanMixLinksAbiv2)
+{
+  InMemorySpanExporter *exporter              = new InMemorySpanExporter();
+  std::shared_ptr<InMemorySpanData> span_data = exporter->GetData();
+  auto tracer                                 = initTracer(std::unique_ptr<SpanExporter>{exporter});
+
+  {
+    // Link 1 added at StartSpan
+    auto span =
+        tracer->StartSpan("span", {{"attr1", 1}}, {{SpanContext(false, false), {{"attr2", 2}}}});
+
+    SpanContext target(false, false);
+    // Link 2 added with AddLink
+    span->AddLink(target, {{"attr3", 3}});
+
+    // Link 3 added with AddLinks
+    span->AddLinks({{SpanContext(false, false), {{"attr4", 4}}}});
+
+    span->End();
+
+    auto spans = span_data->GetSpans();
+    ASSERT_EQ(1, spans.size());
+
+    auto &span_data_links = spans.at(0)->GetLinks();
+    ASSERT_EQ(3, span_data_links.size());
+
+    {
+      auto link  = span_data_links.at(0);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 1);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr2")), 2);
+    }
+
+    {
+      auto link  = span_data_links.at(1);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 1);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr3")), 3);
+    }
+
+    {
+      auto link  = span_data_links.at(2);
+      auto attrs = link.GetAttributes();
+      ASSERT_EQ(attrs.size(), 1);
+      ASSERT_EQ(nostd::get<int>(attrs.at("attr4")), 4);
+    }
+  }
+}
+#endif /* OPENTELEMETRY_ABI_VERSION_NO >= 2 */
+
 TEST(Tracer, TestAlwaysOnSampler)
 {
   InMemorySpanExporter *exporter              = new InMemorySpanExporter();

From cd4d39abfd1ee88a5f9ecdba0c35c0797b0109d2 Mon Sep 17 00:00:00 2001
From: Marc Alff <marc.alff@oracle.com>
Date: Sun, 22 Oct 2023 23:33:04 +0200
Subject: [PATCH 5/8] cleanup

---
 api/include/opentelemetry/trace/default_span.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/api/include/opentelemetry/trace/default_span.h b/api/include/opentelemetry/trace/default_span.h
index 3d0088de0d..7e3979501e 100644
--- a/api/include/opentelemetry/trace/default_span.h
+++ b/api/include/opentelemetry/trace/default_span.h
@@ -51,6 +51,7 @@ class DefaultSpan : public Span
   void AddLink(const SpanContext & /* target */,
                const common::KeyValueIterable & /* attrs */) noexcept override
   {}
+
   void AddLinks(const SpanContextKeyValueIterable & /* links */) noexcept override {}
 #endif
 

From 2cbc4bd034137d585969d447bf5268db8911c9da Mon Sep 17 00:00:00 2001
From: Marc Alff <marc.alff@oracle.com>
Date: Sun, 22 Oct 2023 23:58:28 +0200
Subject: [PATCH 6/8] warning cleanup

---
 examples/plugin/plugin/tracer.cc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/plugin/plugin/tracer.cc b/examples/plugin/plugin/tracer.cc
index 9579d0204e..14d1a746df 100644
--- a/examples/plugin/plugin/tracer.cc
+++ b/examples/plugin/plugin/tracer.cc
@@ -50,8 +50,8 @@ class Span final : public trace::Span
   {}
 
 #if OPENTELEMETRY_ABI_VERSION_NO >= 2
-  void AddLink(const trace::SpanContext &target,
-               const common::KeyValueIterable &attrs) noexcept override
+  void AddLink(const trace::SpanContext & /* target */,
+               const common::KeyValueIterable & /* attrs */) noexcept override
   {}
 
   void AddLinks(const trace::SpanContextKeyValueIterable & /* links */) noexcept override {}

From f4e28a07a70b3b1a06c0c79b7964a443056adf5a Mon Sep 17 00:00:00 2001
From: Marc Alff <marc.alff@oracle.com>
Date: Thu, 26 Oct 2023 20:37:35 +0200
Subject: [PATCH 7/8] Implemented review comments.

---
 api/include/opentelemetry/trace/span.h | 48 ++++++++++++++++++++++++--
 api/test/trace/noop_test.cc            | 15 ++++++++
 2 files changed, 60 insertions(+), 3 deletions(-)

diff --git a/api/include/opentelemetry/trace/span.h b/api/include/opentelemetry/trace/span.h
index 5d5b72f1c9..27e91ceec4 100644
--- a/api/include/opentelemetry/trace/span.h
+++ b/api/include/opentelemetry/trace/span.h
@@ -25,6 +25,31 @@ class Tracer;
 
 /**
  * A Span represents a single operation within a Trace.
+ *
+ * Span attributes can be provided:
+ * - at span creation time, using Tracer::StartSpan(),
+ * - during the span lifetime, using Span::SetAttribute()
+ *
+ * Please note that head samplers,
+ * in the SDK (@ref opentelemetry::sdk::trace::Sampler),
+ * can only make sampling decisions based on data known
+ * at span creation time.
+ *
+ * When attributes are known early, adding attributes
+ * with @ref opentelemetry::trace::Tracer::StartSpan() is preferable.
+ *
+ * Attributes added or changed with Span::SetAttribute()
+ * can not change a sampler decision.
+ *
+ * Likewise, links can be provided:
+ * - at span creation time, using Tracer::StartSpan(),
+ * - during the span lifetime, using Span::AddLink() or Span::AddLinks().
+ *
+ * When links are known early, adding links
+ * with @ref opentelemetry::trace::Tracer::StartSpan() is preferable.
+ *
+ * Links added with Span::AddLink() or Span::AddLinks()
+ * can not change a sampler decision.
  */
 class Span
 {
@@ -42,9 +67,14 @@ class Span
   Span &operator=(const Span &) = delete;
   Span &operator=(Span &&) = delete;
 
-  // Sets an attribute on the Span. If the Span previously contained a mapping
-  // for
-  // the key, the old value is replaced.
+  /**
+   * Sets an attribute on the Span (ABI).
+   *
+   * If the Span previously contained a mapping for the key,
+   * the old value is replaced.
+   *
+   * See comments about sampling in @ref opentelemetry::trace::Span
+   */
   virtual void SetAttribute(nostd::string_view key,
                             const common::AttributeValue &value) noexcept = 0;
 
@@ -105,6 +135,8 @@ class Span
   /**
    * Add link (ABI).
    *
+   * See comments about sampling in @ref opentelemetry::trace::Span
+   *
    * @since ABI_VERSION 2
    */
   virtual void AddLink(const SpanContext &target,
@@ -113,6 +145,8 @@ class Span
   /**
    * Add links (ABI).
    *
+   * See comments about sampling in @ref opentelemetry::trace::Span
+   *
    * @since ABI_VERSION 2
    */
   virtual void AddLinks(const SpanContextKeyValueIterable &links) noexcept = 0;
@@ -120,6 +154,8 @@ class Span
   /**
    * Add link (API helper).
    *
+   * See comments about sampling in @ref opentelemetry::trace::Span
+   *
    * @since ABI_VERSION 2
    */
   template <class U,
@@ -133,6 +169,8 @@ class Span
   /**
    * Add link (API helper).
    *
+   * See comments about sampling in @ref opentelemetry::trace::Span
+   *
    * @since ABI_VERSION 2
    */
   void AddLink(const SpanContext &target,
@@ -153,6 +191,8 @@ class Span
   /**
    * Add links (API helper).
    *
+   * See comments about sampling in @ref opentelemetry::trace::Span
+   *
    * @since ABI_VERSION 2
    */
   template <class U, nostd::enable_if_t<detail::is_span_context_kv_iterable<U>::value> * = nullptr>
@@ -165,6 +205,8 @@ class Span
   /**
    * Add links (API helper).
    *
+   * See comments about sampling in @ref opentelemetry::trace::Span
+   *
    * @since ABI_VERSION 2
    */
   void AddLinks(
diff --git a/api/test/trace/noop_test.cc b/api/test/trace/noop_test.cc
index 130496faf0..b47700d442 100644
--- a/api/test/trace/noop_test.cc
+++ b/api/test/trace/noop_test.cc
@@ -46,6 +46,21 @@ TEST(NoopTest, UseNoopTracers)
   s1->GetContext();
 }
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+TEST(NoopTest, UseNoopTracersAbiv2)
+{
+  std::shared_ptr<trace_api::Tracer> tracer{new trace_api::NoopTracer{}};
+  auto s1 = tracer->StartSpan("abc");
+
+  EXPECT_EQ(s1->IsRecording(), false);
+
+  trace_api::SpanContext target(false, false);
+  s1->AddLink(target, {{"noop1", 1}});
+
+  s1->AddLinks({{trace_api::SpanContext(false, false), {{"noop2", 2}}}});
+}
+#endif /* OPENTELEMETRY_ABI_VERSION_NO >= 2 */
+
 TEST(NoopTest, StartSpan)
 {
   std::shared_ptr<trace_api::Tracer> tracer{new trace_api::NoopTracer{}};

From da23608711ce91f39d2bb429f4a528d7fa347d3e Mon Sep 17 00:00:00 2001
From: Marc Alff <marc.alff@oracle.com>
Date: Fri, 27 Oct 2023 17:41:06 +0200
Subject: [PATCH 8/8] Code cleanup

---
 sdk/src/trace/span.h          | 6 +++---
 sdk/test/trace/tracer_test.cc | 4 ----
 2 files changed, 3 insertions(+), 7 deletions(-)

diff --git a/sdk/src/trace/span.h b/sdk/src/trace/span.h
index bd255b86b6..eb603b9025 100644
--- a/sdk/src/trace/span.h
+++ b/sdk/src/trace/span.h
@@ -42,9 +42,6 @@ class Span final : public opentelemetry::trace::Span
                 opentelemetry::common::SystemTimestamp timestamp,
                 const opentelemetry::common::KeyValueIterable &attributes) noexcept override;
 
-  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;
@@ -52,6 +49,9 @@ class Span final : public opentelemetry::trace::Span
   void AddLinks(const opentelemetry::trace::SpanContextKeyValueIterable &links) noexcept override;
 #endif
 
+  void SetStatus(opentelemetry::trace::StatusCode code,
+                 nostd::string_view description) noexcept override;
+
   void UpdateName(nostd::string_view name) noexcept override;
 
   void End(const opentelemetry::trace::EndSpanOptions &options = {}) noexcept override;
diff --git a/sdk/test/trace/tracer_test.cc b/sdk/test/trace/tracer_test.cc
index 2dd9ace86b..36cc135a1d 100644
--- a/sdk/test/trace/tracer_test.cc
+++ b/sdk/test/trace/tracer_test.cc
@@ -624,9 +624,7 @@ TEST(Tracer, SpanAddLinkAbiv2)
     }
   }
 }
-#endif /* OPENTELEMETRY_ABI_VERSION_NO >= 2 */
 
-#if OPENTELEMETRY_ABI_VERSION_NO >= 2
 TEST(Tracer, SpanAddLinksAbiv2)
 {
   InMemorySpanExporter *exporter              = new InMemorySpanExporter();
@@ -856,9 +854,7 @@ TEST(Tracer, SpanAddLinksAbiv2)
     }
   }
 }
-#endif /* OPENTELEMETRY_ABI_VERSION_NO >= 2 */
 
-#if OPENTELEMETRY_ABI_VERSION_NO >= 2
 TEST(Tracer, SpanMixLinksAbiv2)
 {
   InMemorySpanExporter *exporter              = new InMemorySpanExporter();