feat: Implement Logs Bridge API (open-telemetry#1509)

This provides an interface for:
* LoggerProvider
* Logger
* LogRecord

This API will be consumed by the forthcoming Logs SDK.
Follows specification v 1.23.0.

.github/workflows/ci.yml

@@ -17,6 +17,7 @@ jobs:
         gem:
           - opentelemetry-api
           - opentelemetry-common
+          - opentelemetry-logs-api
           - opentelemetry-metrics-api
           - opentelemetry-registry
           - opentelemetry-sdk

logs_api/lib/opentelemetry-logs-api.rb

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

logs_api/lib/opentelemetry/logs.rb

@@ -4,10 +4,18 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-require 'opentelemetry'
+require_relative 'logs/log_record'
+require_relative 'logs/logger'
+require_relative 'logs/logger_provider'
 
 module OpenTelemetry
-  # OpenTelemetry Logs API
+  # The Logs API records a timestamped record with metadata.
+  # In OpenTelemetry, any data that is not part of a distributed trace or a
+  # metric is a log. For example, events are a specific type of log.
+  #
+  # This API is provided for logging library authors to build log
+  # appenders/bridges. It should NOT be used directly by application
+  # developers.
   module Logs
   end
 end

logs_api/lib/opentelemetry/logs/log_record.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Logs
+    # No-op implementation of an emitted log and its associated attributes.
+    class LogRecord; end
+  end
+end

logs_api/lib/opentelemetry/logs/logger.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Logs
+    # No-op implementation of logger.
+    class Logger
+      # rubocop:disable Style/EmptyMethod
+
+      # Emit a {LogRecord} to the processing pipeline.
+      #
+      # @param timestamp [optional Float, Time] Time in nanoseconds since Unix
+      #   epoch when the event occurred measured by the origin clock, i.e. the
+      #   time at the source.
+      # @param observed_timestamp [optional Float, Time] Time in nanoseconds
+      #   since Unix epoch when the event was observed by the collection system.
+      #   Intended default: Process.clock_gettime(Process::CLOCK_REALTIME)
+      # @param context [optional Context] The Context to associate with the
+      #   LogRecord. Intended default: OpenTelemetry::Context.current
+      # @param severity_number [optional Integer] Numerical value of the
+      #   severity. Smaller numerical values correspond to less severe events
+      #   (such as debug events), larger numerical values correspond to more
+      #   severe events (such as errors and critical events).
+      # @param severity_text [optional String] Original string representation of
+      #   the severity as it is known at the source. Also known as log level.
+      # @param body [optional String, Numeric, Boolean, Array<String, Numeric,
+      #   Boolean>, Hash{String => String, Numeric, Boolean, Array<String,
+      #   Numeric, Boolean>}] A value containing the body of the log record.
+      # @param attributes [optional Hash{String => String, Numeric, Boolean,
+      #   Array<String, Numeric, Boolean>}] Additional information about the
+      #   event.
+      #
+      # @api public
+      def emit(
+        timestamp: nil,
+        observed_timestamp: nil,
+        context: nil,
+        severity_number: nil,
+        severity_text: nil,
+        body: nil,
+        attributes: nil
+      )
+      end
+      # rubocop:enable Style/EmptyMethod
+    end
+  end
+end

logs_api/lib/opentelemetry/logs/logger_provider.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Logs
+    # No-op implementation of a logger provider.
+    class LoggerProvider
+      NOOP_LOGGER = OpenTelemetry::Logs::Logger.new
+      private_constant :NOOP_LOGGER
+
+      # Returns an {OpenTelemetry::Logs::Logger} instance.
+      #
+      # @param [optional String] name Instrumentation package name
+      # @param [optional String] version Instrumentation package version
+      #
+      # @return [OpenTelemetry::Logs::Logger]
+      def logger(name = nil, version = nil)
+        @logger ||= NOOP_LOGGER
+      end
+    end
+  end
+end

logs_api/opentelemetry-logs-api.gemspec

@@ -27,12 +27,12 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'opentelemetry-api', '~> 1.0'
 
   spec.add_development_dependency 'bundler', '>= 1.17'
-  spec.add_development_dependency 'minitest', '~> 5.0'
+  spec.add_development_dependency 'minitest', '~> 5.19'
   spec.add_development_dependency 'rake', '~> 12.0'
-  spec.add_development_dependency 'rubocop', '~> 1.3'
-  spec.add_development_dependency 'simplecov', '~> 0.17'
+  spec.add_development_dependency 'rubocop', '~> 1.55'
+  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'
 
   if spec.respond_to?(:metadata)
     spec.metadata['changelog_uri'] = "https://open-telemetry.github.io/opentelemetry-ruby/opentelemetry-logs-api/v#{OpenTelemetry::Logs::VERSION}/file.CHANGELOG.html"

logs_api/test/.rubocop.yml

@@ -0,0 +1,8 @@
+inherit_from: ../.rubocop.yml
+
+Metrics/BlockLength:
+  Enabled: false
+Metrics/LineLength:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false

logs_api/test/opentelemetry/logs/logger_provider_test.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'test_helper'
+
+describe OpenTelemetry::Logs::LoggerProvider do
+  let(:logger_provider) { OpenTelemetry::Logs::LoggerProvider.new }
+  let(:args) { { name: 'component', version: '1.0' } }
+  let(:args2) { { name: 'component2', version: '1.0' } }
+
+  describe '#logger' do
+    it 'returns the same no-op logger' do
+      assert_same(
+        logger_provider.logger(**args),
+        logger_provider.logger(**args2)
+      )
+    end
+  end
+end

logs_api/test/opentelemetry/logs/logger_test.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'test_helper'
+
+describe OpenTelemetry::Logs::Logger do
+  let(:logger) { OpenTelemetry::Logs::Logger.new }
+
+  describe '#emit' do
+    it 'returns nil, as it is a no-op method' do
+      assert_nil(logger.emit)
+    end
+  end
+end

logs_api/test/test_helper.rb

@@ -5,12 +5,8 @@
 # SPDX-License-Identifier: Apache-2.0
 
 require 'simplecov'
-SimpleCov.start
+SimpleCov.start { enable_coverage :branch }
 SimpleCov.minimum_coverage 85
 
-require 'opentelemetry-test-helpers'
-require 'opentelemetry-metrics-api'
+require 'opentelemetry-logs-api'
 require 'minitest/autorun'
-require 'pry'
-
-OpenTelemetry.logger = Logger.new(File::NULL)