[API] Add InstrumentationScope attributes in TracerProvider::GetTracer()

CHANGELOG.md

@@ -19,9 +19,19 @@ Increment the:
   [#2370](https://github.com/open-telemetry/opentelemetry-cpp/pull/2370)
 * [BUILD] Make WITH_OTLP_HTTP_SSL_PREVIEW mainstream
   [#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)
 
 Important changes:
 
+* [API] Add InstrumentationScope attributes in TracerProvider::GetTracer()
+  [#2371](https://github.com/open-telemetry/opentelemetry-cpp/pull/2371)
+  * TracerProvider::GetTracer() now accepts InstrumentationScope attributes.
+  * 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/trace/noop.h

@@ -108,12 +108,23 @@ class OPENTELEMETRY_EXPORT NoopTracerProvider final : public trace::TracerProvid
       : tracer_{nostd::shared_ptr<trace::NoopTracer>(new trace::NoopTracer)}
   {}
 
-  nostd::shared_ptr<trace::Tracer> GetTracer(nostd::string_view /* library_name */,
-                                             nostd::string_view /* library_version */,
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  nostd::shared_ptr<trace::Tracer> GetTracer(
+      nostd::string_view /* name */,
+      nostd::string_view /* version */,
+      nostd::string_view /* schema_url */,
+      const common::KeyValueIterable * /* attributes */) noexcept override
+  {
+    return tracer_;
+  }
+#else
+  nostd::shared_ptr<trace::Tracer> GetTracer(nostd::string_view /* name */,
+                                             nostd::string_view /* version */,
                                              nostd::string_view /* schema_url */) noexcept override
   {
     return tracer_;
   }
+#endif
 
 private:
   nostd::shared_ptr<trace::Tracer> tracer_;

api/include/opentelemetry/trace/tracer_provider.h

@@ -3,6 +3,8 @@
 
 #pragma once
 
+#include "opentelemetry/common/key_value_iterable.h"
+#include "opentelemetry/common/key_value_iterable_view.h"
 #include "opentelemetry/nostd/shared_ptr.h"
 #include "opentelemetry/nostd/string_view.h"
 #include "opentelemetry/version.h"
@@ -20,15 +22,106 @@ class OPENTELEMETRY_EXPORT TracerProvider
 {
 public:
   virtual ~TracerProvider() = default;
+
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+
+  /**
+   * Gets or creates a named Tracer instance (ABI).
+   *
+   * @since ABI_VERSION 2
+   *
+   * @param[in] name Tracer instrumentation scope
+   * @param[in] version Instrumentation scope version
+   * @param[in] schema_url Instrumentation scope schema URL
+   * @param[in] attributes Instrumentation scope attributes (optional, may be nullptr)
+   */
+  virtual nostd::shared_ptr<Tracer> GetTracer(
+      nostd::string_view name,
+      nostd::string_view version,
+      nostd::string_view schema_url,
+      const common::KeyValueIterable *attributes) noexcept = 0;
+
+  /**
+   * Gets or creates a named Tracer instance (API helper).
+   *
+   * @since ABI_VERSION 2
+   *
+   * @param[in] name Tracer instrumentation scope
+   * @param[in] version Instrumentation scope version, optional
+   * @param[in] schema_url Instrumentation scope schema URL, optional
+   */
+  nostd::shared_ptr<Tracer> GetTracer(nostd::string_view name,
+                                      nostd::string_view version    = "",
+                                      nostd::string_view schema_url = "")
+  {
+    return GetTracer(name, version, schema_url, nullptr);
+  }
+
+  /**
+   * Gets or creates a named Tracer instance (API helper).
+   *
+   * @since ABI_VERSION 2
+   *
+   * @param[in] name Tracer instrumentation scope
+   * @param[in] version Instrumentation scope version
+   * @param[in] schema_url Instrumentation scope schema URL
+   * @param[in] attributes Instrumentation scope attributes
+   */
+  nostd::shared_ptr<Tracer> GetTracer(
+      nostd::string_view name,
+      nostd::string_view version,
+      nostd::string_view schema_url,
+      std::initializer_list<std::pair<nostd::string_view, common::AttributeValue>> attributes)
+  {
+    /* Build a container from std::initializer_list. */
+    nostd::span<const std::pair<nostd::string_view, common::AttributeValue>> attributes_span{
+        attributes.begin(), attributes.end()};
+
+    /* Build a view on the container. */
+    common::KeyValueIterableView<
+        nostd::span<const std::pair<nostd::string_view, common::AttributeValue>>>
+        iterable_attributes{attributes_span};
+
+    /* Add attributes using the view. */
+    return GetTracer(name, version, schema_url, &iterable_attributes);
+  }
+
+  /**
+   * Gets or creates a named Tracer instance (API helper).
+   *
+   * @since ABI_VERSION 2
+   *
+   * @param[in] name Tracer instrumentation scope
+   * @param[in] version Instrumentation scope version
+   * @param[in] schema_url Instrumentation scope schema URL
+   * @param[in] attributes Instrumentation scope attributes container
+   */
+  template <class T,
+            nostd::enable_if_t<common::detail::is_key_value_iterable<T>::value> * = nullptr>
+  nostd::shared_ptr<Tracer> GetTracer(nostd::string_view name,
+                                      nostd::string_view version,
+                                      nostd::string_view schema_url,
+                                      const T &attributes)
+  {
+    /* Build a view on the container. */
+    common::KeyValueIterableView<T> iterable_attributes(attributes);
+
+    /* Add attributes using the view. */
+    return GetTracer(name, version, schema_url, &iterable_attributes);
+  }
+
+#else
+
   /**
    * Gets or creates a named tracer instance.
    *
    * Optionally a version can be passed to create a named and versioned tracer
    * instance.
    */
-  virtual nostd::shared_ptr<Tracer> GetTracer(nostd::string_view library_name,
-                                              nostd::string_view library_version = "",
-                                              nostd::string_view schema_url      = "") noexcept = 0;
+  virtual nostd::shared_ptr<Tracer> GetTracer(nostd::string_view name,
+                                              nostd::string_view version    = "",
+                                              nostd::string_view schema_url = "") noexcept = 0;
+#endif
 };
 }  // namespace trace
 OPENTELEMETRY_END_NAMESPACE

api/test/singleton/singleton_test.cc

@@ -264,13 +264,25 @@ class MyTracerProvider : public trace::TracerProvider
     return result;
   }
 
-  nostd::shared_ptr<trace::Tracer> GetTracer(nostd::string_view /* library_name */,
-                                             nostd::string_view /* library_version */,
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  nostd::shared_ptr<trace::Tracer> GetTracer(
+      nostd::string_view /* name */,
+      nostd::string_view /* version */,
+      nostd::string_view /* schema_url */,
+      const common::KeyValueIterable * /* attributes */) noexcept override
+  {
+    nostd::shared_ptr<trace::Tracer> result(new MyTracer());
+    return result;
+  }
+#else
+  nostd::shared_ptr<trace::Tracer> GetTracer(nostd::string_view /* name */,
+                                             nostd::string_view /* version */,
                                              nostd::string_view /* schema_url */) noexcept override
   {
     nostd::shared_ptr<trace::Tracer> result(new MyTracer());
     return result;
   }
+#endif
 };
 
 void setup_otel()

api/test/trace/provider_test.cc

@@ -3,6 +3,7 @@
 
 #include "opentelemetry/trace/provider.h"
 #include "opentelemetry/nostd/shared_ptr.h"
+#include "opentelemetry/trace/tracer_provider.h"
 
 #include <gtest/gtest.h>
 
@@ -14,12 +15,24 @@ namespace nostd = opentelemetry::nostd;
 
 class TestProvider : public TracerProvider
 {
-  nostd::shared_ptr<Tracer> GetTracer(nostd::string_view /* library_name */,
-                                      nostd::string_view /* library_version */,
+
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  nostd::shared_ptr<Tracer> GetTracer(
+      nostd::string_view /* name */,
+      nostd::string_view /* version */,
+      nostd::string_view /* schema_url */,
+      const opentelemetry::common::KeyValueIterable * /* attributes */) noexcept override
+  {
+    return nostd::shared_ptr<Tracer>(nullptr);
+  }
+#else
+  nostd::shared_ptr<Tracer> GetTracer(nostd::string_view /* name */,
+                                      nostd::string_view /* version */,
                                       nostd::string_view /* schema_url */) noexcept override
   {
     return nostd::shared_ptr<Tracer>(nullptr);
   }
+#endif
 };
 
 TEST(Provider, GetTracerProviderDefault)

sdk/include/opentelemetry/sdk/trace/tracer_provider.h

@@ -63,10 +63,23 @@ class TracerProvider final : public opentelemetry::trace::TracerProvider
 
   ~TracerProvider() override;
 
+  /*
+    Make sure GetTracer() helpers from the API are seen in overload resolution.
+  */
+  using opentelemetry::trace::TracerProvider::GetTracer;
+
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  opentelemetry::nostd::shared_ptr<opentelemetry::trace::Tracer> GetTracer(
+      nostd::string_view name,
+      nostd::string_view version,
+      nostd::string_view schema_url,
+      const opentelemetry::common::KeyValueIterable *attributes) noexcept override;
+#else
   opentelemetry::nostd::shared_ptr<opentelemetry::trace::Tracer> GetTracer(
-      nostd::string_view library_name,
-      nostd::string_view library_version = "",
-      nostd::string_view schema_url      = "") noexcept override;
+      nostd::string_view name,
+      nostd::string_view version    = "",
+      nostd::string_view schema_url = "") noexcept override;
+#endif
 
   /**
    * Attaches a span processor to list of configured processors for this tracer provider.

sdk/src/trace/tracer_provider.cc

@@ -53,17 +53,29 @@ TracerProvider::~TracerProvider()
   }
 }
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
 nostd::shared_ptr<trace_api::Tracer> TracerProvider::GetTracer(
-    nostd::string_view library_name,
-    nostd::string_view library_version,
+    nostd::string_view name,
+    nostd::string_view version,
+    nostd::string_view schema_url,
+    const opentelemetry::common::KeyValueIterable *attributes) noexcept
+#else
+nostd::shared_ptr<trace_api::Tracer> TracerProvider::GetTracer(
+    nostd::string_view name,
+    nostd::string_view version,
     nostd::string_view schema_url) noexcept
+#endif
 {
-  if (library_name.data() == nullptr)
+#if OPENTELEMETRY_ABI_VERSION_NO < 2
+  const opentelemetry::common::KeyValueIterable *attributes = nullptr;
+#endif
+
+  if (name.data() == nullptr)
   {
     OTEL_INTERNAL_LOG_ERROR("[TracerProvider::GetTracer] Library name is null.");
-    library_name = "";
+    name = "";
   }
-  else if (library_name == "")
+  else if (name == "")
   {
     OTEL_INTERNAL_LOG_ERROR("[TracerProvider::GetTracer] Library name is empty.");
   }
@@ -72,17 +84,20 @@ nostd::shared_ptr<trace_api::Tracer> TracerProvider::GetTracer(
 
   for (auto &tracer : tracers_)
   {
-    auto &tracer_lib = tracer->GetInstrumentationScope();
-    if (tracer_lib.equal(library_name, library_version, schema_url))
+    auto &tracer_scope = tracer->GetInstrumentationScope();
+    if (tracer_scope.equal(name, version, schema_url))
     {
       return nostd::shared_ptr<trace_api::Tracer>{tracer};
     }
   }
 
-  auto lib = InstrumentationScope::Create(library_name, library_version, schema_url);
-  tracers_.push_back(std::shared_ptr<opentelemetry::sdk::trace::Tracer>(
-      new sdk::trace::Tracer(context_, std::move(lib))));
-  return nostd::shared_ptr<trace_api::Tracer>{tracers_.back()};
+  instrumentationscope::InstrumentationScopeAttributes attrs_map(attributes);
+  auto scope =
+      instrumentationscope::InstrumentationScope::Create(name, version, schema_url, attrs_map);
+
+  auto tracer = std::shared_ptr<Tracer>(new Tracer(context_, std::move(scope)));
+  tracers_.push_back(tracer);
+  return nostd::shared_ptr<trace_api::Tracer>{tracer};
 }
 
 void TracerProvider::AddProcessor(std::unique_ptr<SpanProcessor> processor) noexcept