feat: Create Logs SDK LoggerProvider (#1517)

* feat: Create Logs SDK LoggerProvider

* Add OpenTelemetry::SDK::Logs::Export constants
* Create OpenTelemetry::SDK::Logs::LoggerProvider
* Implement LoggerProvider#logger
* Implement LoggerProvider#shutdown
* Implement LoggerProvider#force_flush
* Create no-op LogRecordProcessor

* Update Export module description

* Update #on_emit context arg description

* Remove public reader for log_record_processors

* LoggerProvider#logger: keyword args, require name

* Remove attr_readers for scope and provider

* Apply suggestions from code review

Co-authored-by: Francis Bogsanyi <[email protected]>

* Remove unncessary error handling

* Warn #add_log_record_processor calls when stopped

* Remove "optional" marker from type description

Co-authored-by: Olle Jonsson <[email protected]>

* Remove "optional" from type documentation

* Apply suggestions from code review

Co-authored-by: Francis Bogsanyi <[email protected]>

* Apply suggestions from code review

Co-authored-by: Francis Bogsanyi <[email protected]>

---------

Co-authored-by: Francis Bogsanyi <[email protected]>
Co-authored-by: Olle Jonsson <[email protected]>

logs_sdk/Gemfile

@@ -7,3 +7,8 @@
 source 'https://rubygems.org'
 
 gemspec
+
+gem 'opentelemetry-api', path: '../api'
+gem 'opentelemetry-logs-api', path: '../logs_api'
+gem 'opentelemetry-sdk', path: '../sdk'
+gem 'opentelemetry-test-helpers', path: '../test_helpers'

logs_sdk/lib/opentelemetry-logs-sdk.rb

@@ -4,5 +4,5 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+require 'opentelemetry/sdk'
 require 'opentelemetry/sdk/logs'
-require 'opentelemetry/sdk/logs/version'

logs_sdk/lib/opentelemetry/sdk/logs.rb

@@ -5,6 +5,10 @@
 # SPDX-License-Identifier: Apache-2.0
 
 require_relative 'logs/version'
+require_relative 'logs/logger'
+require_relative 'logs/logger_provider'
+require_relative 'logs/log_record_processor'
+require_relative 'logs/export'
 
 module OpenTelemetry
   module SDK

logs_sdk/lib/opentelemetry/sdk/logs/export.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Logs
+      # The Export module contains result codes for exporters
+      module Export
+        # The operation finished successfully.
+        SUCCESS = 0
+
+        # The operation finished with an error.
+        FAILURE = 1
+
+        # The operation timed out.
+        TIMEOUT = 2
+      end
+    end
+  end
+end

logs_sdk/lib/opentelemetry/sdk/logs/log_record_processor.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Logs
+      # LogRecordProcessor describes a duck type and provides a synchronous no-op hook for when a
+      # {LogRecord} is emitted. It is not required to subclass this
+      # class to provide an implementation of LogRecordProcessor, provided the interface is
+      # satisfied.
+      class LogRecordProcessor
+        # Called when a {LogRecord} is emitted. Subsequent calls are not
+        # permitted after shutdown is called.
+        # @param [LogRecord] log_record The emitted {LogRecord}
+        # @param [Context] context The {Context}
+        def on_emit(log_record, context); end
+
+        # Export all log records to the configured `Exporter` that have not yet
+        # been exported.
+        #
+        # This method should only be called in cases where it is absolutely
+        # necessary, such as when using some FaaS providers that may suspend
+        # the process after an invocation, but before the `Processor` exports
+        # the completed spans.
+        #
+        # @param [Numeric] timeout An optional timeout in seconds.
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
+        def force_flush(timeout: nil)
+          Export::SUCCESS
+        end
+
+        # Called when {LoggerProvider#shutdown} is called.
+        #
+        # @param [Numeric] timeout An optional timeout in seconds.
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
+        def shutdown(timeout: nil)
+          Export::SUCCESS
+        end
+      end
+    end
+  end
+end

logs_sdk/lib/opentelemetry/sdk/logs/logger.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Logs
+      # The SDK implementation of OpenTelemetry::Logs::Logger
+      class Logger < OpenTelemetry::Logs::Logger
+        # @api private
+        #
+        # Returns a new {OpenTelemetry::SDK::Logs::Logger} instance. This should
+        # not be called directly. New loggers should be created using
+        # {LoggerProvider#logger}.
+        #
+        # @param [String] name Instrumentation package name
+        # @param [String] version Instrumentation package version
+        # @param [LoggerProvider] logger_provider The {LoggerProvider} that
+        #   initialized the logger
+        #
+        # @return [OpenTelemetry::SDK::Logs::Logger]
+        def initialize(name, version, logger_provider)
+          @instrumentation_scope = InstrumentationScope.new(name, version)
+          @logger_provider = logger_provider
+        end
+      end
+    end
+  end
+end

logs_sdk/lib/opentelemetry/sdk/logs/logger_provider.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module SDK
+    module Logs
+      # The SDK implementation of OpenTelemetry::Logs::LoggerProvider.
+      class LoggerProvider < OpenTelemetry::Logs::LoggerProvider
+        attr_reader :resource
+
+        UNEXPECTED_ERROR_MESSAGE = 'unexpected error in ' \
+          'OpenTelemetry::SDK::Logs::LoggerProvider#%s'
+
+        private_constant :UNEXPECTED_ERROR_MESSAGE
+
+        # Returns a new LoggerProvider instance.
+        #
+        # @param [optional Resource] resource The resource to associate with
+        #   new LogRecords created by {Logger}s created by this LoggerProvider.
+        #
+        # @return [OpenTelemetry::SDK::Logs::LoggerProvider]
+        def initialize(resource: OpenTelemetry::SDK::Resources::Resource.create)
+          @log_record_processors = []
+          @mutex = Mutex.new
+          @resource = resource
+          @stopped = false
+        end
+
+        # Returns an {OpenTelemetry::SDK::Logs::Logger} instance.
+        #
+        # @param [String] name Instrumentation package name
+        # @param [optional String] version Instrumentation package version
+        #
+        # @return [OpenTelemetry::SDK::Logs::Logger]
+        def logger(name:, version: nil)
+          version ||= ''
+
+          if !name.is_a?(String) || name.empty?
+            OpenTelemetry.logger.warn('LoggerProvider#logger called with an ' \
+              "invalid name. Name provided: #{name.inspect}")
+          end
+
+         Logger.new(name, version, self)
+        end
+
+        # Adds a new log record processor to this LoggerProvider's
+        # log_record_processors.
+        #
+        # @param [LogRecordProcessor] log_record_processor The
+        #   {LogRecordProcessor} to add to this LoggerProvider.
+        def add_log_record_processor(log_record_processor)
+          @mutex.synchronize do
+            if @stopped
+              OpenTelemetry.logger.warn('calling LoggerProvider#' \
+                'add_log_record_processor after shutdown.')
+              return
+            end
+            @log_record_processors = @log_record_processors.dup.push(log_record_processor)
+          end
+        end
+
+        # Attempts to stop all the activity for this LoggerProvider. Calls
+        # {LogRecordProcessor#shutdown} for all registered {LogRecordProcessor}s.
+        #
+        # This operation may block until all log records are processed. Must
+        # be called before turning off the main application to ensure all data
+        # are processed and exported.
+        #
+        # After this is called all newly created {LogRecord}s will be no-op.
+        #
+        # @param [optional Numeric] timeout An optional timeout in seconds.
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
+        def shutdown(timeout: nil)
+          @mutex.synchronize do
+            if @stopped
+              OpenTelemetry.logger.warn('LoggerProvider#shutdown called multiple times.')
+              return Export::FAILURE
+            end
+
+            start_time = OpenTelemetry::Common::Utilities.timeout_timestamp
+            results = @log_record_processors.map do |processor|
+              remaining_timeout = OpenTelemetry::Common::Utilities.maybe_timeout(timeout, start_time)
+              break [Export::TIMEOUT] if remaining_timeout&.zero?
+
+              processor.shutdown(timeout: remaining_timeout)
+            end
+
+            @stopped = true
+            results.max || Export::SUCCESS
+          end
+        end
+
+        # Immediately export all {LogRecord}s that have not yet been exported
+        # for all the registered {LogRecordProcessor}s.
+        #
+        # This method should only be called in cases where it is absolutely
+        # necessary, such as when using some FaaS providers that may suspend
+        # the process after an invocation, but before the {LogRecordProcessor}
+        # exports the completed {LogRecord}s.
+        #
+        # @param [optional Numeric] timeout An optional timeout in seconds.
+        # @return [Integer] Export::SUCCESS if no error occurred, Export::FAILURE if
+        #   a non-specific failure occurred, Export::TIMEOUT if a timeout occurred.
+        def force_flush(timeout: nil)
+          @mutex.synchronize do
+            return Export::SUCCESS if @stopped
+
+            start_time = OpenTelemetry::Common::Utilities.timeout_timestamp
+            results = @log_record_processors.map do |processor|
+              remaining_timeout = OpenTelemetry::Common::Utilities.maybe_timeout(timeout, start_time)
+              return Export::TIMEOUT if remaining_timeout&.zero?
+
+              processor.force_flush(timeout: remaining_timeout)
+            end
+
+            results.max || Export::SUCCESS
+          end
+        end
+      end
+    end
+  end
+end

logs_sdk/opentelemetry-logs-sdk.gemspec

@@ -24,15 +24,18 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 3.0'
 
-  spec.add_dependency 'opentelemetry-logs-api', '~> 0.1.0'
+  spec.add_dependency 'opentelemetry-api', '~> 1.2'
+  spec.add_dependency 'opentelemetry-logs-api', '~> 0.1'
+  spec.add_dependency 'opentelemetry-sdk', '~> 1.3'
 
   spec.add_development_dependency 'bundler', '>= 1.17'
-  spec.add_development_dependency 'minitest', '~> 5.0'
-  spec.add_development_dependency 'rake', '~> 12.0'
-  spec.add_development_dependency 'rubocop', '~> 1.51.0'
-  spec.add_development_dependency 'simplecov', '~> 0.17'
+  spec.add_development_dependency 'minitest', '~> 5.19'
+  spec.add_development_dependency 'opentelemetry-test-helpers', '~> 0.4'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rubocop', '~> 1.56'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
   spec.add_development_dependency 'yard', '~> 0.9'
-  spec.add_development_dependency 'yard-doctest', '~> 0.1.6'
+  spec.add_development_dependency 'yard-doctest', '~> 0.1.17'
 
   if spec.respond_to?(:metadata)
     spec.metadata['changelog_uri'] = "https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-logs-sdk/v#{OpenTelemetry::SDK::Logs::VERSION}/file.CHANGELOG.html"

logs_sdk/test/.rubocop.yml

@@ -1,24 +1,8 @@
-# inherit_from: .rubocop_todo.yml
+inherit_from: ../.rubocop.yml
 
-AllCops:
-  TargetRubyVersion: '3.0'
-
-Lint/UnusedMethodArgument:
-  Enabled: false
-Metrics/AbcSize:
+Metrics/BlockLength:
   Enabled: false
 Metrics/LineLength:
   Enabled: false
-Metrics/MethodLength:
-  Max: 50
-Metrics/PerceivedComplexity:
-  Max: 30
-Metrics/CyclomaticComplexity:
-  Max: 20
-Metrics/ParameterLists:
-  Enabled: false
-Naming/FileName:
-  Exclude:
-    - 'lib/opentelemetry-logs-sdk.rb'
-Style/ModuleFunction:
+Metrics/AbcSize:
   Enabled: false