[SDK] Add tracer scope configurator

CHANGELOG.md

@@ -27,6 +27,9 @@ Increment the:
 * [SEMANTIC CONVENTIONS] Migration to weaver
   [#3105](https://github.com/open-telemetry/opentelemetry-cpp/pull/3105)
 
+* [SDK] Add tracer scope configurator
+  [#3137](https://github.com/open-telemetry/opentelemetry-cpp/pull/3137)
+
 Important changes:
 
 * [API] Jaeger Propagator should not be deprecated

sdk/include/opentelemetry/sdk/instrumentationscope/instrumentation_scope.h

@@ -3,6 +3,7 @@
 
 #pragma once
 
+#include <functional>
 #include <string>
 #include <type_traits>
 
@@ -158,6 +159,8 @@ class InstrumentationScope
   InstrumentationScopeAttributes attributes_;
 };
 
+template <class T>
+using ScopeConfigurator = std::function<T(const InstrumentationScope &)>;
 }  // namespace instrumentationscope
 }  // namespace sdk
 

sdk/include/opentelemetry/sdk/trace/tracer.h

@@ -13,7 +13,9 @@
 #include "opentelemetry/sdk/trace/id_generator.h"
 #include "opentelemetry/sdk/trace/processor.h"
 #include "opentelemetry/sdk/trace/sampler.h"
+#include "opentelemetry/sdk/trace/tracer_config.h"
 #include "opentelemetry/sdk/trace/tracer_context.h"
+#include "opentelemetry/trace/noop.h"
 #include "opentelemetry/trace/span.h"
 #include "opentelemetry/trace/span_context_kv_iterable.h"
 #include "opentelemetry/trace/span_startoptions.h"
@@ -103,8 +105,10 @@ class Tracer final : public opentelemetry::trace::Tracer,
 private:
   // order of declaration is important here - instrumentation scope should destroy after
   // tracer-context.
+  std::unique_ptr<TracerConfig> tracer_config_;
   std::shared_ptr<InstrumentationScope> instrumentation_scope_;
   std::shared_ptr<TracerContext> context_;
+  static const std::shared_ptr<opentelemetry::trace::NoopTracer> kNoopTracer;
 };
 }  // namespace trace
 }  // namespace sdk

sdk/include/opentelemetry/sdk/trace/tracer_config.h

@@ -0,0 +1,71 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include "opentelemetry/sdk/instrumentationscope/instrumentation_scope.h"
+#include "opentelemetry/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace trace
+{
+/**
+ * TracerConfig defines various configurable aspects of a Tracer's behavior.
+ * This class should not be used directly to configure a Tracer's behavior, instead a
+ * ScopeConfigurator should be used to compute the desired TracerConfig which can then be used to
+ * configure a Tracer.
+ */
+class TracerConfig
+{
+public:
+  bool operator==(const TracerConfig &other) const noexcept;
+
+  /**
+   * Returns if the Tracer is enabled or disabled. Tracers are enabled by default.
+   * @return a boolean indicating if the Tracer is enabled. Defaults to true.
+   */
+  bool IsEnabled() const noexcept;
+
+  /**
+   * Returns a TracerConfig that represents a disabled Tracer. A disabled tracer behaves like a
+   * no-op tracer.
+   * @return a static constant TracerConfig that represents a disabled tracer.
+   */
+  static TracerConfig Disabled();
+
+  /**
+   * Returns a TracerConfig that represents an enabled Tracer.
+   * @return a static constant TracerConfig that represents an enabled tracer.
+   */
+  static TracerConfig Enabled();
+
+  /**
+   * Returns a TracerConfig that represents a Tracer configured with the default behavior.
+   * The default behavior is guided by the OpenTelemetry specification.
+   * @return a static constant TracerConfig that represents a tracer configured with default
+   * behavior.
+   */
+  static TracerConfig Default();
+
+  /**
+   * Returns a ScopeConfigurator that can be used to get the default tracer configurator.
+   * A tracer configurator computes TracerConfig based on the InstrumentationScope. The default
+   * tracer configurator unconditionally computes the default TracerConfig for all scopes.
+   *
+   * @return a static constant TracerConfig that represents a tracer configurator with default
+   * behavior.
+   */
+  static const instrumentationscope::ScopeConfigurator<TracerConfig> &DefaultConfigurator();
+
+private:
+  explicit TracerConfig(const bool disabled = false) : disabled_(disabled) {}
+  bool disabled_;
+  static const TracerConfig kDefaultConfig;
+  static const TracerConfig kDisabledConfig;
+  static const instrumentationscope::ScopeConfigurator<TracerConfig> kDefaultTracerConfigurator;
+};
+}  // namespace trace
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE

sdk/include/opentelemetry/sdk/trace/tracer_context.h

@@ -13,6 +13,7 @@
 #include "opentelemetry/sdk/trace/random_id_generator.h"
 #include "opentelemetry/sdk/trace/sampler.h"
 #include "opentelemetry/sdk/trace/samplers/always_on.h"
+#include "opentelemetry/sdk/trace/tracer_config.h"
 #include "opentelemetry/version.h"
 
 OPENTELEMETRY_BEGIN_NAMESPACE
@@ -21,6 +22,8 @@ namespace sdk
 namespace trace
 {
 
+using namespace opentelemetry::sdk::instrumentationscope;
+
 /**
  * A class which stores the TracerProvider context.
  *
@@ -43,7 +46,10 @@ class TracerContext
           opentelemetry::sdk::resource::Resource::Create({}),
       std::unique_ptr<Sampler> sampler = std::unique_ptr<AlwaysOnSampler>(new AlwaysOnSampler),
       std::unique_ptr<IdGenerator> id_generator =
-          std::unique_ptr<IdGenerator>(new RandomIdGenerator())) noexcept;
+          std::unique_ptr<IdGenerator>(new RandomIdGenerator()),
+      std::unique_ptr<instrumentationscope::ScopeConfigurator<TracerConfig>> tracer_configurator =
+          std::make_unique<instrumentationscope::ScopeConfigurator<TracerConfig>>(
+              TracerConfig::DefaultConfigurator())) noexcept;
 
   virtual ~TracerContext() = default;
 
@@ -77,6 +83,8 @@ class TracerContext
    */
   const opentelemetry::sdk::resource::Resource &GetResource() const noexcept;
 
+  instrumentationscope::ScopeConfigurator<TracerConfig> &GetTracerConfigurator() const noexcept;
+
   /**
    * Obtain the Id Generator associated with this tracer context.
    * @return The ID Generator for this tracer context.
@@ -100,6 +108,7 @@ class TracerContext
   std::unique_ptr<Sampler> sampler_;
   std::unique_ptr<IdGenerator> id_generator_;
   std::unique_ptr<SpanProcessor> processor_;
+  std::unique_ptr<instrumentationscope::ScopeConfigurator<TracerConfig>> tracer_configurator_;
 };
 
 }  // namespace trace

sdk/include/opentelemetry/sdk/trace/tracer_context_factory.h

@@ -54,6 +54,16 @@ class OPENTELEMETRY_EXPORT TracerContextFactory
       const opentelemetry::sdk::resource::Resource &resource,
       std::unique_ptr<Sampler> sampler,
       std::unique_ptr<IdGenerator> id_generator);
+
+  /**
+   * Create a TracerContext.
+   */
+  static std::unique_ptr<TracerContext> Create(
+      std::vector<std::unique_ptr<SpanProcessor>> &&processors,
+      const opentelemetry::sdk::resource::Resource &resource,
+      std::unique_ptr<Sampler> sampler,
+      std::unique_ptr<IdGenerator> id_generator,
+      std::unique_ptr<instrumentationscope::ScopeConfigurator<TracerConfig>> tracer_configurator);
 };
 
 }  // namespace trace

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

@@ -27,6 +27,8 @@ namespace sdk
 namespace trace
 {
 
+using namespace opentelemetry::sdk::instrumentationscope;
+
 class OPENTELEMETRY_EXPORT TracerProvider final : public opentelemetry::trace::TracerProvider
 {
 public:
@@ -39,22 +41,30 @@ class OPENTELEMETRY_EXPORT TracerProvider final : public opentelemetry::trace::T
    * not be a nullptr.
    * @param id_generator The custom id generator for this tracer provider. This must
    * not be a nullptr
+   * @param tracer_configurator Provides access to a function that computes the TracerConfig for
+   * Tracers provided by this TracerProvider.
    */
   explicit TracerProvider(
       std::unique_ptr<SpanProcessor> processor,
       const opentelemetry::sdk::resource::Resource &resource =
           opentelemetry::sdk::resource::Resource::Create({}),
       std::unique_ptr<Sampler> sampler = std::unique_ptr<AlwaysOnSampler>(new AlwaysOnSampler),
       std::unique_ptr<IdGenerator> id_generator =
-          std::unique_ptr<IdGenerator>(new RandomIdGenerator())) noexcept;
+          std::unique_ptr<IdGenerator>(new RandomIdGenerator()),
+      std::unique_ptr<instrumentationscope::ScopeConfigurator<TracerConfig>> tracer_configurator =
+          std::make_unique<instrumentationscope::ScopeConfigurator<TracerConfig>>(
+              TracerConfig::DefaultConfigurator())) noexcept;
 
   explicit TracerProvider(
       std::vector<std::unique_ptr<SpanProcessor>> &&processors,
       const opentelemetry::sdk::resource::Resource &resource =
           opentelemetry::sdk::resource::Resource::Create({}),
       std::unique_ptr<Sampler> sampler = std::unique_ptr<AlwaysOnSampler>(new AlwaysOnSampler),
       std::unique_ptr<IdGenerator> id_generator =
-          std::unique_ptr<IdGenerator>(new RandomIdGenerator())) noexcept;
+          std::unique_ptr<IdGenerator>(new RandomIdGenerator()),
+      std::unique_ptr<instrumentationscope::ScopeConfigurator<TracerConfig>> tracer_configurator =
+          std::make_unique<instrumentationscope::ScopeConfigurator<TracerConfig>>(
+              TracerConfig::DefaultConfigurator())) noexcept;
 
   /**
    * Initialize a new tracer provider with a specified context

sdk/include/opentelemetry/sdk/trace/tracer_provider_factory.h

@@ -28,7 +28,7 @@ namespace trace
 class OPENTELEMETRY_EXPORT TracerProviderFactory
 {
 public:
-  /* Serie of builders with a single processor. */
+  /* Series of creator methods with a single processor. */
 
   static std::unique_ptr<opentelemetry::sdk::trace::TracerProvider> Create(
       std::unique_ptr<SpanProcessor> processor);
@@ -48,7 +48,14 @@ class OPENTELEMETRY_EXPORT TracerProviderFactory
       std::unique_ptr<Sampler> sampler,
       std::unique_ptr<IdGenerator> id_generator);
 
-  /* Serie of builders with a vector of processor. */
+  static std::unique_ptr<opentelemetry::sdk::trace::TracerProvider> Create(
+      std::unique_ptr<SpanProcessor> processor,
+      const opentelemetry::sdk::resource::Resource &resource,
+      std::unique_ptr<Sampler> sampler,
+      std::unique_ptr<IdGenerator> id_generator,
+      std::unique_ptr<instrumentationscope::ScopeConfigurator<TracerConfig>> tracer_configurator);
+
+  /* Series of creator methods with a single processor. */
 
   static std::unique_ptr<opentelemetry::sdk::trace::TracerProvider> Create(
       std::vector<std::unique_ptr<SpanProcessor>> &&processors);
@@ -68,6 +75,13 @@ class OPENTELEMETRY_EXPORT TracerProviderFactory
       std::unique_ptr<Sampler> sampler,
       std::unique_ptr<IdGenerator> id_generator);
 
+  static std::unique_ptr<opentelemetry::sdk::trace::TracerProvider> Create(
+      std::vector<std::unique_ptr<SpanProcessor>> &&processors,
+      const opentelemetry::sdk::resource::Resource &resource,
+      std::unique_ptr<Sampler> sampler,
+      std::unique_ptr<IdGenerator> id_generator,
+      std::unique_ptr<instrumentationscope::ScopeConfigurator<TracerConfig>> tracer_configurator);
+
   /* Create with a tracer context. */
 
   static std::unique_ptr<opentelemetry::sdk::trace::TracerProvider> Create(

sdk/src/trace/CMakeLists.txt

@@ -20,7 +20,8 @@ add_library(
   samplers/trace_id_ratio.cc
   samplers/trace_id_ratio_factory.cc
   random_id_generator.cc
-  random_id_generator_factory.cc)
+  random_id_generator_factory.cc
+  tracer_config.cc)
 
 set_target_properties(opentelemetry_trace PROPERTIES EXPORT_NAME trace)
 set_target_version(opentelemetry_trace)

sdk/src/trace/tracer.cc

@@ -3,6 +3,7 @@
 
 #include <stdint.h>
 #include <chrono>
+#include <functional>
 #include <map>
 #include <new>
 #include <utility>
@@ -16,6 +17,7 @@
 #include "opentelemetry/sdk/trace/id_generator.h"
 #include "opentelemetry/sdk/trace/sampler.h"
 #include "opentelemetry/sdk/trace/tracer.h"
+#include "opentelemetry/sdk/trace/tracer_config.h"
 #include "opentelemetry/sdk/trace/tracer_context.h"
 #include "opentelemetry/trace/context.h"
 #include "opentelemetry/trace/noop.h"
@@ -36,11 +38,16 @@ namespace sdk
 {
 namespace trace
 {
+const std::shared_ptr<opentelemetry::trace::NoopTracer> Tracer::kNoopTracer =
+    std::make_shared<opentelemetry::trace::NoopTracer>();
 
 Tracer::Tracer(std::shared_ptr<TracerContext> context,
                std::unique_ptr<InstrumentationScope> instrumentation_scope) noexcept
     : instrumentation_scope_{std::move(instrumentation_scope)}, context_{std::move(context)}
-{}
+{
+  tracer_config_ =
+      std::make_unique<TracerConfig>(context_->GetTracerConfigurator()(*instrumentation_scope_));
+}
 
 nostd::shared_ptr<opentelemetry::trace::Span> Tracer::StartSpan(
     nostd::string_view name,
@@ -51,6 +58,10 @@ nostd::shared_ptr<opentelemetry::trace::Span> Tracer::StartSpan(
   opentelemetry::trace::SpanContext parent_context = GetCurrentSpan()->GetContext();
   if (nostd::holds_alternative<opentelemetry::trace::SpanContext>(options.parent))
   {
+    if (!tracer_config_->IsEnabled())
+    {
+      return kNoopTracer->StartSpan(name, attributes, links, options);
+    }
     auto span_context = nostd::get<opentelemetry::trace::SpanContext>(options.parent);
     if (span_context.IsValid())
     {

sdk/src/trace/tracer_config.cc

@@ -0,0 +1,52 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+#include "opentelemetry/sdk/trace/tracer_config.h"
+#include "opentelemetry/sdk/instrumentationscope/instrumentation_scope.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace trace
+{
+
+const TracerConfig TracerConfig::kDefaultConfig  = TracerConfig();
+const TracerConfig TracerConfig::kDisabledConfig = TracerConfig(true);
+
+const instrumentationscope::ScopeConfigurator<TracerConfig>
+    TracerConfig::kDefaultTracerConfigurator =
+        [](const instrumentationscope::InstrumentationScope &) { return Default(); };
+
+TracerConfig TracerConfig::Disabled()
+{
+  return kDisabledConfig;
+}
+
+TracerConfig TracerConfig::Enabled()
+{
+  return kDefaultConfig;
+}
+
+TracerConfig TracerConfig::Default()
+{
+  return kDefaultConfig;
+}
+
+const instrumentationscope::ScopeConfigurator<TracerConfig> &TracerConfig::DefaultConfigurator()
+{
+  return kDefaultTracerConfigurator;
+}
+
+bool TracerConfig::IsEnabled() const noexcept
+{
+  return !disabled_;
+}
+
+bool TracerConfig::operator==(const TracerConfig &other) const noexcept
+{
+  return disabled_ == other.disabled_;
+}
+
+}  // namespace trace
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE