[API] Add Enabled method to Tracer (open-telemetry#3357)

Author: psx95

CHANGELOG.md

@@ -21,6 +21,9 @@ Increment the:
 * [CMAKE] Bump cmake minimum required version to 3.14
   [#3349](https://github.com/open-telemetry/opentelemetry-cpp/pull/3349)
 
+* [API] Add Enabled method to Tracer
+  [#3357](https://github.com/open-telemetry/opentelemetry-cpp/pull/3357)
+
 ## [1.20 2025-04-01]
 
 * [BUILD] Update opentelemetry-proto version

api/include/opentelemetry/common/macros.h

@@ -341,7 +341,7 @@ point.
 // Atomic wrappers based on compiler intrinsics for memory read/write.
 // The tailing number is read/write length in bits.
 //
-// N.B. Compiler instrinsic is used because the usage of C++ standard library is restricted in the
+// N.B. Compiler intrinsic is used because the usage of C++ standard library is restricted in the
 // OpenTelemetry C++ API.
 //
 #if defined(__GNUC__)

api/include/opentelemetry/plugin/tracer.h

@@ -87,7 +87,11 @@ class Tracer final : public trace::Tracer, public std::enable_shared_from_this<T
   Tracer(std::shared_ptr<DynamicLibraryHandle> library_handle,
          std::unique_ptr<TracerHandle> &&tracer_handle) noexcept
       : library_handle_{std::move(library_handle)}, tracer_handle_{std::move(tracer_handle)}
-  {}
+  {
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+    UpdateEnabled(true);
+#endif
+  }
 
   // trace::Tracer
   nostd::shared_ptr<trace::Span> StartSpan(

api/include/opentelemetry/trace/noop.h

@@ -96,6 +96,13 @@ class OPENTELEMETRY_EXPORT NoopTracer final : public Tracer,
 {
 public:
   // Tracer
+  NoopTracer()
+  {
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+    UpdateEnabled(false);
+#endif
+  }
+
   nostd::shared_ptr<Span> StartSpan(nostd::string_view /*name*/,
                                     const common::KeyValueIterable & /*attributes*/,
                                     const SpanContextKeyValueIterable & /*links*/,

api/include/opentelemetry/trace/tracer.h

@@ -163,6 +163,18 @@ class Tracer
     }
   }
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  /**
+   * Reports if the tracer is enabled or not. A disabled tracer will not create spans.
+   *
+   * The instrumentation authors should call this method before creating a spans to
+   * potentially avoid performing computationally expensive operations for disabled tracers.
+   *
+   * @since ABI_VERSION 2
+   */
+  bool Enabled() const noexcept { return OPENTELEMETRY_ATOMIC_READ_8(&this->enabled_) != 0; }
+#endif
+
 #if OPENTELEMETRY_ABI_VERSION_NO == 1
 
   /*
@@ -197,6 +209,36 @@ class Tracer
   virtual void CloseWithMicroseconds(uint64_t timeout) noexcept = 0;
 
 #endif /* OPENTELEMETRY_ABI_VERSION_NO */
+
+protected:
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+
+  /**
+   * Updates the enabled state of the tracer. Calling this method will affect the result of the
+   * subsequent calls to {@code opentelemetry::v2::trace::Tracer::Enabled()}.
+   *
+   * This method should be used by SDK implementations to indicate the tracer's updated state
+   * whenever a tracer transitions from enabled to disabled state and vice versa.
+   *
+   * @param enabled The new state of the tracer. False would indicate that the tracer is no longer
+   * enabled and will not produce as
+   *
+   * @since ABI_VERSION 2
+   */
+  void UpdateEnabled(const bool enabled) noexcept
+  {
+    OPENTELEMETRY_ATOMIC_WRITE_8(&this->enabled_, enabled);
+  }
+#endif
+
+private:
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  // Variable to support implementation of Enabled method introduced in ABI V2.
+  // Mutable allows enabled_ to be used as 'bool *' (instead of 'const bool *'), with the
+  // OPENTELEMETRY_ATOMIC_READ_8 macro's internal casts when used from a const function.
+  // std::atomic can not be used here because it is not ABI compatible for OpenTelemetry C++ API.
+  mutable bool enabled_ = true;
+#endif
 };
 }  // namespace trace
 OPENTELEMETRY_END_NAMESPACE

api/test/singleton/singleton_test.cc

@@ -169,6 +169,13 @@ void reset_counts()
 class MyTracer : public trace::Tracer
 {
 public:
+  MyTracer()
+  {
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+    UpdateEnabled(true);
+#endif
+  }
+
   nostd::shared_ptr<trace::Span> StartSpan(
       nostd::string_view name,
       const common::KeyValueIterable & /* attributes */,

api/test/trace/noop_test.cc

@@ -70,6 +70,8 @@ TEST(NoopTest, UseNoopTracersAbiv2)
   s1->AddLink(target, {{"noop1", 1}});
 
   s1->AddLinks({{trace_api::SpanContext(false, false), {{"noop2", 2}}}});
+
+  EXPECT_FALSE(tracer->Enabled());
 }
 #endif /* OPENTELEMETRY_ABI_VERSION_NO >= 2 */
 

examples/plugin/plugin/tracer.cc

@@ -81,7 +81,12 @@ class Span final : public trace::Span
 };
 }  // namespace
 
-Tracer::Tracer(nostd::string_view /*output*/) {}
+Tracer::Tracer(nostd::string_view /*output*/)
+{
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  UpdateEnabled(true);
+#endif
+}
 
 nostd::shared_ptr<trace::Span> Tracer::StartSpan(nostd::string_view name,
                                                  const common::KeyValueIterable &attributes,

exporters/etw/include/opentelemetry/exporters/etw/etw_tracer.h

@@ -590,6 +590,20 @@ class Tracer : public opentelemetry::trace::Tracer,
     return result;
   }
 
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  /**
+   * Reports if the tracer is enabled or not. A disabled tracer will not create spans.
+   * Note: The etw_tracer currently does not accept a TracerConfig and can therefore not be disabled
+   * based on the instrumentation scope.
+   *
+   * The instrumentation authors should call this method before creating a spans to
+   * potentially avoid performing computationally expensive operations for disabled tracers.
+   *
+   * @since ABI_VERSION 2
+   */
+  virtual bool Enabled() const noexcept { return true; }
+#endif
+
 #if OPENTELEMETRY_ABI_VERSION_NO == 1
   /**
    * @brief Force flush data to Tracer, spending up to given amount of microseconds to flush.

sdk/src/trace/tracer.cc

@@ -46,7 +46,11 @@ Tracer::Tracer(std::shared_ptr<TracerContext> context,
     : instrumentation_scope_{std::move(instrumentation_scope)},
       context_{std::move(context)},
       tracer_config_(context_->GetTracerConfigurator().ComputeConfig(*instrumentation_scope_))
-{}
+{
+#if OPENTELEMETRY_ABI_VERSION_NO >= 2
+  UpdateEnabled(tracer_config_.IsEnabled());
+#endif
+}
 
 nostd::shared_ptr<opentelemetry::trace::Span> Tracer::StartSpan(
     nostd::string_view name,