[SDK] Add logger scope configurator (open-telemetry#3282)

Author: psx95

CHANGELOG.md

@@ -27,6 +27,9 @@ Increment the:
 * [DEVCONTAINER] Support customization and run as non-root user
   [#3270](https://github.com/open-telemetry/opentelemetry-cpp/pull/3270)
 
+* [SDK] Add logger scope configurator
+  [#3282](https://github.com/open-telemetry/opentelemetry-cpp/pull/3282)
+
 Important changes:
 
 * [SDK] Support OTEL_SDK_DISABLED environment variable

sdk/include/opentelemetry/sdk/logs/logger.h

@@ -6,8 +6,10 @@
 #include <memory>
 #include <string>
 
+#include "logger_config.h"
 #include "opentelemetry/logs/log_record.h"
 #include "opentelemetry/logs/logger.h"
+#include "opentelemetry/logs/noop.h"
 #include "opentelemetry/nostd/string_view.h"
 #include "opentelemetry/nostd/unique_ptr.h"
 #include "opentelemetry/sdk/instrumentationscope/instrumentation_scope.h"
@@ -65,6 +67,8 @@ class Logger final : public opentelemetry::logs::Logger
   // logger-context.
   std::unique_ptr<instrumentationscope::InstrumentationScope> instrumentation_scope_;
   std::shared_ptr<LoggerContext> context_;
+  LoggerConfig logger_config_;
+  static opentelemetry::logs::NoopLogger kNoopLogger;
 };
 
 }  // namespace logs

sdk/include/opentelemetry/sdk/logs/logger_config.h

@@ -0,0 +1,58 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#include "opentelemetry/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace logs
+{
+/**
+ * LoggerConfig defines various configurable aspects of a Logger's behavior.
+ * This class should not be used directly to configure a Logger's behavior, instead a
+ * ScopeConfigurator should be used to compute the desired LoggerConfig which can then be used to
+ * configure a Logger.
+ */
+class OPENTELEMETRY_EXPORT LoggerConfig
+{
+public:
+  bool operator==(const LoggerConfig &other) const noexcept;
+
+  /**
+   * Returns if the Logger is enabled or disabled. Loggers are enabled by default.
+   * @return a boolean indicating if the Logger is enabled. Defaults to true.
+   */
+  bool IsEnabled() const noexcept;
+
+  /**
+   * Returns a LoggerConfig that represents an enabled Logger.
+   * @return a static constant LoggerConfig that represents an enabled logger.
+   */
+  static LoggerConfig Enabled();
+
+  /**
+   * Returns a LoggerConfig that represents a disabled Logger. A disabled logger behaves like a
+   * no-op logger.
+   * @return a static constant LoggerConfig that represents a disabled logger.
+   */
+  static LoggerConfig Disabled();
+
+  /**
+   * Returns a LoggerConfig that represents a Logger configured with the default behavior.
+   * The default behavior is guided by the OpenTelemetry specification.
+   * @return a static constant LoggerConfig that represents a logger configured with default
+   * behavior.
+   */
+  static LoggerConfig Default();
+
+private:
+  explicit LoggerConfig(const bool disabled = false) : disabled_(disabled) {}
+
+  bool disabled_;
+};
+}  // namespace logs
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE

sdk/include/opentelemetry/sdk/logs/logger_context.h

@@ -7,6 +7,8 @@
 #include <memory>
 #include <vector>
 
+#include "logger_config.h"
+#include "opentelemetry/sdk/instrumentationscope/scope_configurator.h"
 #include "opentelemetry/sdk/logs/processor.h"
 #include "opentelemetry/sdk/resource/resource.h"
 #include "opentelemetry/version.h"
@@ -33,9 +35,15 @@ namespace logs
 class LoggerContext
 {
 public:
-  explicit LoggerContext(std::vector<std::unique_ptr<LogRecordProcessor>> &&processors,
-                         const opentelemetry::sdk::resource::Resource &resource =
-                             opentelemetry::sdk::resource::Resource::Create({})) noexcept;
+  explicit LoggerContext(
+      std::vector<std::unique_ptr<LogRecordProcessor>> &&processors,
+      const opentelemetry::sdk::resource::Resource &resource =
+          opentelemetry::sdk::resource::Resource::Create({}),
+      std::unique_ptr<instrumentationscope::ScopeConfigurator<LoggerConfig>> logger_configurator =
+          std::make_unique<instrumentationscope::ScopeConfigurator<LoggerConfig>>(
+              instrumentationscope::ScopeConfigurator<LoggerConfig>::Builder(
+                  LoggerConfig::Default())
+                  .Build())) noexcept;
 
   /**
    * Attaches a log processor to list of configured processors to this logger context.
@@ -61,6 +69,13 @@ class LoggerContext
    */
   const opentelemetry::sdk::resource::Resource &GetResource() const noexcept;
 
+  /**
+   * Obtain the ScopeConfigurator with this logger context.
+   * @return The ScopeConfigurator for this logger context.
+   */
+  const instrumentationscope::ScopeConfigurator<LoggerConfig> &GetLoggerConfigurator()
+      const noexcept;
+
   /**
    * Force all active LogProcessors to flush any buffered logs
    * within the given timeout.
@@ -76,6 +91,8 @@ class LoggerContext
   //  order of declaration is important here - resource object should be destroyed after processor.
   opentelemetry::sdk::resource::Resource resource_;
   std::unique_ptr<LogRecordProcessor> processor_;
+
+  std::unique_ptr<instrumentationscope::ScopeConfigurator<LoggerConfig>> logger_configurator_;
 };
 }  // namespace logs
 }  // namespace sdk

sdk/include/opentelemetry/sdk/logs/logger_context_factory.h

@@ -24,17 +24,36 @@ class LoggerContextFactory
 {
 public:
   /**
-   * Create a LoggerContext.
+   * Create a LoggerContext with specified LogRecordProcessors.
+   * @param processors A vector of log processors that can parse the logs.
+   * @return A unique pointer to the created LoggerContext object.
    */
   static std::unique_ptr<LoggerContext> Create(
       std::vector<std::unique_ptr<LogRecordProcessor>> &&processors);
 
   /**
-   * Create a LoggerContext.
+   * Create a LoggerContext with specified LogRecordProcessors and OpenTelemetry resource.
+   * @param processors A vector of log processors that can parse the logs.
+   * @param resource The OpenTelemetry resource responsible for generating the logs.
+   * @return A unique pointer to the created LoggerContext object.
    */
   static std::unique_ptr<LoggerContext> Create(
       std::vector<std::unique_ptr<LogRecordProcessor>> &&processors,
       const opentelemetry::sdk::resource::Resource &resource);
+
+  /**
+   * Create a LoggerContext with specified LogRecordProcessors, OpenTelemetry resource and a logger
+   * ScopeConfigurator.
+   * @param processors A vector of log processors that can parse the logs.
+   * @param resource The OpenTelemetry resource responsible for generating the logs.
+   * @param logger_configurator A ScopeConfigurator that can be used compute the LoggerConfig for a
+   * given InstrumentationScope.
+   * @return A unique pointer to the created LoggerContext object.
+   */
+  static std::unique_ptr<LoggerContext> Create(
+      std::vector<std::unique_ptr<LogRecordProcessor>> &&processors,
+      const opentelemetry::sdk::resource::Resource &resource,
+      std::unique_ptr<instrumentationscope::ScopeConfigurator<LoggerConfig>> logger_configurator);
 };
 
 }  // namespace logs

sdk/include/opentelemetry/sdk/logs/logger_provider.h

@@ -32,18 +32,37 @@ class OPENTELEMETRY_EXPORT LoggerProvider final : public opentelemetry::logs::Lo
 {
 public:
   /**
-   * Initialize a new logger provider
-   * @param processor The span processor for this logger provider. This must
+   * Initialize a new logger provider.
+   * @param processor The log record processor for this logger provider. This must
    * not be a nullptr.
    * @param resource  The resources for this logger provider.
    */
-  explicit LoggerProvider(std::unique_ptr<LogRecordProcessor> &&processor,
-                          const opentelemetry::sdk::resource::Resource &resource =
-                              opentelemetry::sdk::resource::Resource::Create({})) noexcept;
+  explicit LoggerProvider(
+      std::unique_ptr<LogRecordProcessor> &&processor,
+      const opentelemetry::sdk::resource::Resource &resource =
+          opentelemetry::sdk::resource::Resource::Create({}),
+      std::unique_ptr<instrumentationscope::ScopeConfigurator<LoggerConfig>> logger_configurator =
+          std::make_unique<instrumentationscope::ScopeConfigurator<LoggerConfig>>(
+              instrumentationscope::ScopeConfigurator<LoggerConfig>::Builder(
+                  LoggerConfig::Default())
+                  .Build())) noexcept;
 
-  explicit LoggerProvider(std::vector<std::unique_ptr<LogRecordProcessor>> &&processors,
-                          const opentelemetry::sdk::resource::Resource &resource =
-                              opentelemetry::sdk::resource::Resource::Create({})) noexcept;
+  /**
+   * Initialize a new logger provider.
+   * @param processors A list of log record processors for this logger provider.
+   * @param resource  The resources for this logger provider.
+   * @param logger_configurator The scope configurator used to determine the configs for loggers
+   * created using this logger provider.
+   */
+  explicit LoggerProvider(
+      std::vector<std::unique_ptr<LogRecordProcessor>> &&processors,
+      const opentelemetry::sdk::resource::Resource &resource =
+          opentelemetry::sdk::resource::Resource::Create({}),
+      std::unique_ptr<instrumentationscope::ScopeConfigurator<LoggerConfig>> logger_configurator =
+          std::make_unique<instrumentationscope::ScopeConfigurator<LoggerConfig>>(
+              instrumentationscope::ScopeConfigurator<LoggerConfig>::Builder(
+                  LoggerConfig::Default())
+                  .Build())) noexcept;
 
   /**
    * Initialize a new logger provider. A processor must later be assigned

sdk/include/opentelemetry/sdk/logs/logger_provider_factory.h

@@ -37,6 +37,14 @@ class OPENTELEMETRY_EXPORT LoggerProviderFactory
       std::unique_ptr<LogRecordProcessor> &&processor,
       const opentelemetry::sdk::resource::Resource &resource);
 
+  /**
+   * Create a LoggerProvider.
+   */
+  static std::unique_ptr<opentelemetry::sdk::logs::LoggerProvider> Create(
+      std::unique_ptr<LogRecordProcessor> &&processor,
+      const opentelemetry::sdk::resource::Resource &resource,
+      std::unique_ptr<instrumentationscope::ScopeConfigurator<LoggerConfig>> logger_configurator);
+
   /**
    * Create a LoggerProvider.
    */
@@ -50,6 +58,14 @@ class OPENTELEMETRY_EXPORT LoggerProviderFactory
       std::vector<std::unique_ptr<LogRecordProcessor>> &&processors,
       const opentelemetry::sdk::resource::Resource &resource);
 
+  /**
+   * Create a LoggerProvider.
+   */
+  static std::unique_ptr<opentelemetry::sdk::logs::LoggerProvider> Create(
+      std::vector<std::unique_ptr<LogRecordProcessor>> &&processors,
+      const opentelemetry::sdk::resource::Resource &resource,
+      std::unique_ptr<instrumentationscope::ScopeConfigurator<LoggerConfig>> logger_configurator);
+
   /**
    * Create a LoggerProvider.
    */

sdk/src/logs/CMakeLists.txt

@@ -15,6 +15,7 @@ add_library(
   simple_log_record_processor_factory.cc
   batch_log_record_processor.cc
   batch_log_record_processor_factory.cc
+  logger_config.cc
   logger_context.cc
   logger_context_factory.cc
   multi_log_record_processor.cc

sdk/src/logs/logger.cc

@@ -9,12 +9,15 @@
 #include "opentelemetry/context/context_value.h"
 #include "opentelemetry/context/runtime_context.h"
 #include "opentelemetry/logs/log_record.h"
+#include "opentelemetry/logs/noop.h"
 #include "opentelemetry/nostd/shared_ptr.h"
 #include "opentelemetry/nostd/string_view.h"
 #include "opentelemetry/nostd/unique_ptr.h"
 #include "opentelemetry/nostd/variant.h"
 #include "opentelemetry/sdk/instrumentationscope/instrumentation_scope.h"
+#include "opentelemetry/sdk/instrumentationscope/scope_configurator.h"
 #include "opentelemetry/sdk/logs/logger.h"
+#include "opentelemetry/sdk/logs/logger_config.h"
 #include "opentelemetry/sdk/logs/logger_context.h"
 #include "opentelemetry/sdk/logs/processor.h"
 #include "opentelemetry/sdk/logs/recordable.h"
@@ -31,22 +34,34 @@ namespace logs
 namespace trace_api = opentelemetry::trace;
 namespace common    = opentelemetry::common;
 
+opentelemetry::logs::NoopLogger Logger::kNoopLogger = opentelemetry::logs::NoopLogger();
+
 Logger::Logger(
     opentelemetry::nostd::string_view name,
     std::shared_ptr<LoggerContext> context,
     std::unique_ptr<instrumentationscope::InstrumentationScope> instrumentation_scope) noexcept
     : logger_name_(std::string(name)),
       instrumentation_scope_(std::move(instrumentation_scope)),
-      context_(std::move(context))
+      context_(std::move(context)),
+      logger_config_(context_->GetLoggerConfigurator().ComputeConfig(*instrumentation_scope_))
 {}
 
 const opentelemetry::nostd::string_view Logger::GetName() noexcept
 {
+  if (!logger_config_.IsEnabled())
+  {
+    return kNoopLogger.GetName();
+  }
   return logger_name_;
 }
 
 opentelemetry::nostd::unique_ptr<opentelemetry::logs::LogRecord> Logger::CreateLogRecord() noexcept
 {
+  if (!logger_config_.IsEnabled())
+  {
+    return kNoopLogger.CreateLogRecord();
+  }
+
   auto recordable = context_->GetProcessor().MakeRecordable();
 
   recordable->SetObservedTimestamp(std::chrono::system_clock::now());
@@ -90,6 +105,11 @@ opentelemetry::nostd::unique_ptr<opentelemetry::logs::LogRecord> Logger::CreateL
 void Logger::EmitLogRecord(
     opentelemetry::nostd::unique_ptr<opentelemetry::logs::LogRecord> &&log_record) noexcept
 {
+  if (!logger_config_.IsEnabled())
+  {
+    return kNoopLogger.EmitLogRecord(std::move(log_record));
+  }
+
   if (!log_record)
   {
     return;

sdk/src/logs/logger_config.cc

@@ -0,0 +1,41 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+#include "opentelemetry/sdk/logs/logger_config.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace sdk
+{
+namespace logs
+{
+
+OPENTELEMETRY_EXPORT bool LoggerConfig::operator==(const LoggerConfig &other) const noexcept
+{
+  return disabled_ == other.disabled_;
+}
+
+OPENTELEMETRY_EXPORT bool LoggerConfig::IsEnabled() const noexcept
+{
+  return !disabled_;
+}
+
+OPENTELEMETRY_EXPORT LoggerConfig LoggerConfig::Enabled()
+{
+  return Default();
+}
+
+OPENTELEMETRY_EXPORT LoggerConfig LoggerConfig::Disabled()
+{
+  static const auto kDisabledConfig = LoggerConfig(true);
+  return kDisabledConfig;
+}
+
+OPENTELEMETRY_EXPORT LoggerConfig LoggerConfig::Default()
+{
+  static const auto kDefaultConfig = LoggerConfig();
+  return kDefaultConfig;
+}
+
+}  // namespace logs
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE