[API/SDK] Provider cleanup

CHANGELOG.md

@@ -21,6 +21,52 @@ Increment the:
 * [CI] Upgrade to clang-format 18
   [#2684](https://github.com/open-telemetry/opentelemetry-cpp/pull/2684)
 
+* [API/SDK] Provider cleanup
+  [#2664](https://github.com/open-telemetry/opentelemetry-cpp/pull/2664)
+
+Important changes:
+
+* [API/SDK] Provider cleanup
+  [#2664](https://github.com/open-telemetry/opentelemetry-cpp/pull/2664)
+  * Before this fix:
+    * The API class `opentelemetry::trace::Tracer` exposed methods such
+      as `ForceFlush()`, `ForceFlushWithMicroseconds()`, `Close()`
+      and `CloseWithMicroseconds()`.
+    * These methods are meant to be used when configuring the SDK,
+      and should not be part of the API. Exposing them was an oversight.
+    * Two of these methods are virtual, and therefore part of the ABI.
+  * After this fix:
+    * In `OPENTELEMETRY_ABI_VERSION_NO 1`, nothing is changed,
+      because removing this code would break the ABI.
+    * In `OPENTELEMETRY_ABI_VERSION_NO 2`, these methods are moved
+      from the API to the SDK. This is a breaking change for ABI version 2,
+      which is still experimental.
+  * In all cases, instrumenting an application should not
+    invoke flush or close on a tracer, do not use these methods.
+
+Breaking changes:
+
+* [API/SDK] Provider cleanup
+  [#2664](https://github.com/open-telemetry/opentelemetry-cpp/pull/2664)
+  * Before this fix:
+    * SDK factory methods such as:
+      * opentelemetry::sdk::trace::TracerProviderFactory::Create()
+      * opentelemetry::sdk::metrics::MeterProviderFactory::Create()
+      * opentelemetry::sdk::logs::LoggerProviderFactory::Create()
+      * opentelemetry::sdk::logs::EventLoggerProviderFactory::Create()
+      returned an API object (opentelemetry::trace::TracerProvider)
+      to the caller.
+  * After this fix, these methods return an SDK level object
+    (opentelemetry::sdk::trace::TracerProvider) to the caller.
+  * Returning an SDK object is necessary for the application to
+    cleanup and invoke SDK level methods, such as ForceFlush(),
+    on a provider.
+  * The application code that configures the SDK, by calling
+    the various provider factories, may need adjustment.
+  * All the examples have been updated, and in particular no
+    longer perform static_cast do convert an API object to an SDK object.
+    Please refer to examples for guidance on how to adjust.
+
 Notes on experimental features:
 
 * [#2372](https://github.com/open-telemetry/opentelemetry-cpp/issues/2372)

api/include/opentelemetry/plugin/tracer.h

@@ -104,6 +104,8 @@ class Tracer final : public trace::Tracer, public std::enable_shared_from_this<T
     return nostd::shared_ptr<trace::Span>{new (std::nothrow) Span{this->shared_from_this(), span}};
   }
 
+#if OPENTELEMETRY_ABI_VERSION_NO == 1
+
   void ForceFlushWithMicroseconds(uint64_t timeout) noexcept override
   {
     tracer_handle_->tracer().ForceFlushWithMicroseconds(timeout);
@@ -114,6 +116,8 @@ class Tracer final : public trace::Tracer, public std::enable_shared_from_this<T
     tracer_handle_->tracer().CloseWithMicroseconds(timeout);
   }
 
+#endif /* OPENTELEMETRY_ABI_VERSION_NO */
+
 private:
   // Note: The order is important here.
   //

api/include/opentelemetry/trace/noop.h

@@ -102,9 +102,13 @@ class OPENTELEMETRY_EXPORT NoopTracer final : public Tracer,
     return noop_span;
   }
 
+#if OPENTELEMETRY_ABI_VERSION_NO == 1
+
   void ForceFlushWithMicroseconds(uint64_t /*timeout*/) noexcept override {}
 
   void CloseWithMicroseconds(uint64_t /*timeout*/) noexcept override {}
+
+#endif /* OPENTELEMETRY_ABI_VERSION_NO */
 };
 
 /**

api/include/opentelemetry/trace/tracer.h

@@ -163,6 +163,13 @@ class Tracer
     }
   }
 
+#if OPENTELEMETRY_ABI_VERSION_NO == 1
+
+  /*
+   * The following is removed from the API in ABI version 2.
+   * It belongs to the SDK.
+   */
+
   /**
    * Force any buffered spans to flush.
    * @param timeout to complete the flush
@@ -188,6 +195,8 @@ class Tracer
   }
 
   virtual void CloseWithMicroseconds(uint64_t timeout) noexcept = 0;
+
+#endif /* OPENTELEMETRY_ABI_VERSION_NO */
 };
 }  // namespace trace
 OPENTELEMETRY_END_NAMESPACE

api/test/singleton/singleton_test.cc

@@ -250,9 +250,13 @@ class MyTracer : public trace::Tracer
     return result;
   }
 
+#if OPENTELEMETRY_ABI_VERSION_NO == 1
+
   void ForceFlushWithMicroseconds(uint64_t /* timeout */) noexcept override {}
 
   void CloseWithMicroseconds(uint64_t /* timeout */) noexcept override {}
+
+#endif /* OPENTELEMETRY_ABI_VERSION_NO */
 };
 
 class MyTracerProvider : public trace::TracerProvider

examples/logs_simple/main.cc

@@ -1,19 +1,20 @@
 // Copyright The OpenTelemetry Authors
 // SPDX-License-Identifier: Apache-2.0
 
+#include "opentelemetry/exporters/ostream/log_record_exporter.h"
 #include "opentelemetry/exporters/ostream/span_exporter_factory.h"
+#include "opentelemetry/logs/provider.h"
+#include "opentelemetry/sdk/logs/logger_provider.h"
+#include "opentelemetry/sdk/logs/logger_provider_factory.h"
+#include "opentelemetry/sdk/logs/processor.h"
+#include "opentelemetry/sdk/logs/simple_log_record_processor_factory.h"
 #include "opentelemetry/sdk/trace/exporter.h"
 #include "opentelemetry/sdk/trace/processor.h"
 #include "opentelemetry/sdk/trace/simple_processor_factory.h"
+#include "opentelemetry/sdk/trace/tracer_provider.h"
 #include "opentelemetry/sdk/trace/tracer_provider_factory.h"
 #include "opentelemetry/trace/provider.h"
 
-#include "opentelemetry/exporters/ostream/log_record_exporter.h"
-#include "opentelemetry/logs/provider.h"
-#include "opentelemetry/sdk/logs/logger_provider_factory.h"
-#include "opentelemetry/sdk/logs/processor.h"
-#include "opentelemetry/sdk/logs/simple_log_record_processor_factory.h"
-
 #ifdef BAZEL_BUILD
 #  include "examples/common/logs_foo_library/foo_library.h"
 #else
@@ -35,11 +36,12 @@ void InitTracer()
   // Create ostream span exporter instance
   auto exporter  = trace_exporter::OStreamSpanExporterFactory::Create();
   auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));
-  std::shared_ptr<trace_api::TracerProvider> provider =
+  std::shared_ptr<trace_sdk::TracerProvider> provider =
       trace_sdk::TracerProviderFactory::Create(std::move(processor));
 
   // Set the global trace provider
-  trace_api::Provider::SetTracerProvider(provider);
+  std::shared_ptr<trace_api::TracerProvider> api_provider = provider;
+  trace_api::Provider::SetTracerProvider(api_provider);
 }
 
 void CleanupTracer()
@@ -54,11 +56,12 @@ void InitLogger()
   auto exporter =
       std::unique_ptr<logs_sdk::LogRecordExporter>(new logs_exporter::OStreamLogRecordExporter);
   auto processor = logs_sdk::SimpleLogRecordProcessorFactory::Create(std::move(exporter));
-  std::shared_ptr<logs_api::LoggerProvider> provider(
+  std::shared_ptr<logs_sdk::LoggerProvider> provider(
       logs_sdk::LoggerProviderFactory::Create(std::move(processor)));
 
   // Set the global logger provider
-  logs_api::Provider::SetLoggerProvider(provider);
+  std::shared_ptr<logs_api::LoggerProvider> api_provider = provider;
+  logs_api::Provider::SetLoggerProvider(api_provider);
 }
 
 void CleanupLogger()

examples/metrics_simple/metrics_ostream.cc

@@ -46,10 +46,9 @@ void InitMetrics(const std::string &name)
   auto reader =
       metrics_sdk::PeriodicExportingMetricReaderFactory::Create(std::move(exporter), options);
 
-  auto u_provider = metrics_sdk::MeterProviderFactory::Create();
-  auto *p         = static_cast<metrics_sdk::MeterProvider *>(u_provider.get());
+  auto provider = metrics_sdk::MeterProviderFactory::Create();
 
-  p->AddMetricReader(std::move(reader));
+  provider->AddMetricReader(std::move(reader));
 
   // counter view
   std::string counter_name = name + "_counter";
@@ -63,7 +62,7 @@ void InitMetrics(const std::string &name)
   auto sum_view = metrics_sdk::ViewFactory::Create(name, "description", unit,
                                                    metrics_sdk::AggregationType::kSum);
 
-  p->AddView(std::move(instrument_selector), std::move(meter_selector), std::move(sum_view));
+  provider->AddView(std::move(instrument_selector), std::move(meter_selector), std::move(sum_view));
 
   // observable counter view
   std::string observable_counter_name = name + "_observable_counter";
@@ -76,8 +75,8 @@ void InitMetrics(const std::string &name)
   auto observable_sum_view = metrics_sdk::ViewFactory::Create(name, "test_description", unit,
                                                               metrics_sdk::AggregationType::kSum);
 
-  p->AddView(std::move(observable_instrument_selector), std::move(observable_meter_selector),
-             std::move(observable_sum_view));
+  provider->AddView(std::move(observable_instrument_selector), std::move(observable_meter_selector),
+                    std::move(observable_sum_view));
 
   // histogram view
   std::string histogram_name = name + "_histogram";
@@ -100,11 +99,11 @@ void InitMetrics(const std::string &name)
   auto histogram_view = metrics_sdk::ViewFactory::Create(
       name, "description", unit, metrics_sdk::AggregationType::kHistogram, aggregation_config);
 
-  p->AddView(std::move(histogram_instrument_selector), std::move(histogram_meter_selector),
-             std::move(histogram_view));
+  provider->AddView(std::move(histogram_instrument_selector), std::move(histogram_meter_selector),
+                    std::move(histogram_view));
 
-  std::shared_ptr<opentelemetry::metrics::MeterProvider> provider(std::move(u_provider));
-  metrics_api::Provider::SetMeterProvider(provider);
+  std::shared_ptr<opentelemetry::metrics::MeterProvider> api_provider(std::move(provider));
+  metrics_api::Provider::SetMeterProvider(api_provider);
 }
 
 void CleanupMetrics()

examples/otlp/file_log_main.cc

@@ -8,20 +8,17 @@
 #include "opentelemetry/exporters/otlp/otlp_file_log_record_exporter_options.h"
 #include "opentelemetry/logs/provider.h"
 #include "opentelemetry/sdk/logs/exporter.h"
+#include "opentelemetry/sdk/logs/logger_provider.h"
 #include "opentelemetry/sdk/logs/logger_provider_factory.h"
 #include "opentelemetry/sdk/logs/processor.h"
 #include "opentelemetry/sdk/logs/simple_log_record_processor_factory.h"
 #include "opentelemetry/sdk/trace/exporter.h"
 #include "opentelemetry/sdk/trace/processor.h"
 #include "opentelemetry/sdk/trace/simple_processor_factory.h"
+#include "opentelemetry/sdk/trace/tracer_provider.h"
 #include "opentelemetry/sdk/trace/tracer_provider_factory.h"
 #include "opentelemetry/trace/provider.h"
 
-// sdk::TracerProvider and sdk::LoggerProvider is just used to call ForceFlush and prevent to cancel
-// running exportings when destroy and shutdown exporters.It's optional to users.
-#include "opentelemetry/sdk/logs/logger_provider.h"
-#include "opentelemetry/sdk/trace/tracer_provider.h"
-
 #include <iostream>
 #include <string>
 #include <utility>
@@ -43,52 +40,55 @@ namespace
 {
 opentelemetry::exporter::otlp::OtlpFileExporterOptions opts;
 opentelemetry::exporter::otlp::OtlpFileLogRecordExporterOptions log_opts;
+
+std::shared_ptr<opentelemetry::sdk::trace::TracerProvider> tracer_provider;
+std::shared_ptr<opentelemetry::sdk::logs::LoggerProvider> logger_provider;
+
 void InitTracer()
 {
   // Create OTLP exporter instance
-  auto exporter  = otlp::OtlpFileExporterFactory::Create(opts);
-  auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));
-  std::shared_ptr<opentelemetry::trace::TracerProvider> provider =
-      trace_sdk::TracerProviderFactory::Create(std::move(processor));
+  auto exporter   = otlp::OtlpFileExporterFactory::Create(opts);
+  auto processor  = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));
+  tracer_provider = trace_sdk::TracerProviderFactory::Create(std::move(processor));
+
   // Set the global trace provider
-  trace::Provider::SetTracerProvider(provider);
+  std::shared_ptr<opentelemetry::trace::TracerProvider> api_provider = tracer_provider;
+  trace::Provider::SetTracerProvider(api_provider);
 }
 
 void CleanupTracer()
 {
   // We call ForceFlush to prevent to cancel running exportings, It's optional.
-  opentelemetry::nostd::shared_ptr<opentelemetry::trace::TracerProvider> provider =
-      trace::Provider::GetTracerProvider();
-  if (provider)
+  if (tracer_provider)
   {
-    static_cast<trace_sdk::TracerProvider *>(provider.get())->ForceFlush();
+    tracer_provider->ForceFlush();
   }
 
+  tracer_provider.reset();
   std::shared_ptr<opentelemetry::trace::TracerProvider> none;
   trace::Provider::SetTracerProvider(none);
 }
 
 void InitLogger()
 {
   // Create OTLP exporter instance
-  auto exporter  = otlp::OtlpFileLogRecordExporterFactory::Create(log_opts);
-  auto processor = logs_sdk::SimpleLogRecordProcessorFactory::Create(std::move(exporter));
-  nostd::shared_ptr<logs::LoggerProvider> provider(
-      logs_sdk::LoggerProviderFactory::Create(std::move(processor)));
+  auto exporter   = otlp::OtlpFileLogRecordExporterFactory::Create(log_opts);
+  auto processor  = logs_sdk::SimpleLogRecordProcessorFactory::Create(std::move(exporter));
+  logger_provider = logs_sdk::LoggerProviderFactory::Create(std::move(processor));
 
-  opentelemetry::logs::Provider::SetLoggerProvider(provider);
+  std::shared_ptr<opentelemetry::logs::LoggerProvider> api_provider = logger_provider;
+  opentelemetry::logs::Provider::SetLoggerProvider(api_provider);
 }
 
 void CleanupLogger()
 {
   // We call ForceFlush to prevent to cancel running exportings, It's optional.
-  opentelemetry::nostd::shared_ptr<logs::LoggerProvider> provider =
-      logs::Provider::GetLoggerProvider();
-  if (provider)
+  if (logger_provider)
   {
-    static_cast<logs_sdk::LoggerProvider *>(provider.get())->ForceFlush();
+    logger_provider->ForceFlush();
   }
 
+  logger_provider.reset();
   nostd::shared_ptr<logs::LoggerProvider> none;
   opentelemetry::logs::Provider::SetLoggerProvider(none);
 }

examples/otlp/file_main.cc

@@ -28,27 +28,30 @@ namespace otlp      = opentelemetry::exporter::otlp;
 namespace
 {
 opentelemetry::exporter::otlp::OtlpFileExporterOptions opts;
+
+std::shared_ptr<opentelemetry::sdk::trace::TracerProvider> provider;
+
 void InitTracer()
 {
   // Create OTLP exporter instance
   auto exporter  = otlp::OtlpFileExporterFactory::Create(opts);
   auto processor = trace_sdk::SimpleSpanProcessorFactory::Create(std::move(exporter));
-  std::shared_ptr<opentelemetry::trace::TracerProvider> provider =
-      trace_sdk::TracerProviderFactory::Create(std::move(processor));
+  provider       = trace_sdk::TracerProviderFactory::Create(std::move(processor));
+
   // Set the global trace provider
-  trace::Provider::SetTracerProvider(provider);
+  std::shared_ptr<opentelemetry::trace::TracerProvider> api_provider = provider;
+  trace::Provider::SetTracerProvider(api_provider);
 }
 
 void CleanupTracer()
 {
   // We call ForceFlush to prevent to cancel running exportings, It's optional.
-  opentelemetry::nostd::shared_ptr<opentelemetry::trace::TracerProvider> provider =
-      trace::Provider::GetTracerProvider();
   if (provider)
   {
-    static_cast<trace_sdk::TracerProvider *>(provider.get())->ForceFlush();
+    provider->ForceFlush(std::chrono::milliseconds(10000));
   }
 
+  provider.reset();
   std::shared_ptr<opentelemetry::trace::TracerProvider> none;
   trace::Provider::SetTracerProvider(none);
 }