opentelemetry-logs-api 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bb876f294a02c1026da26c1a98277ce60065b6e324e6238fcee7247c60d3ce5
-  data.tar.gz: 96ab1e1de9ce4de79d5429137f3b278f411d8aafab130810afffc66e3ba6d2d6
+  metadata.gz: 9b79311663b08bc24f42364c95dc9e9ad7661305c1133fc4055325812a875acd
+  data.tar.gz: 15ffffa097e04d769baafcdef433516ff1ee6da3e958e048b0b8594299e711a0
 SHA512:
-  metadata.gz: 23424a9c4603838ab3dcdae3f181030ac7b240d9db0f248d717c4f4bc830baf747af8b3937690d4eefd4d633d7b984c33dcf0cc632efdae78f34d7c7925ccc0b
-  data.tar.gz: 498f5aa0e3a5f9c86fe94b1d4a7e081acc1cb2cb68311e2f9285dacefed147114c4bda2384c26f73c059e7edf7148c50f414a7face7d8855c9c7ac0da0d412ce
+  metadata.gz: 8189d762e8015fe69d8a892df36a85a87f49fd3b13ca567e62f1a0f8f9cfebd96010156c1f26c6d6e21c3d540eaf6c3535a06c08a1f0c73afb2ab36d54426145
+  data.tar.gz: 0bc233125c84872680eb184293616b22afd3be29262d001ac0502c8b8afeab06c308f172535fb4dd82694e4c06b2c1497f0ebfcf4a05fbcefc8fc264b995aa01

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Release History: opentelemetry-logs-api
 
+### v0.6.0 / 2026-10-05
+
+* BREAKING CHANGE: Move the global logger provider behind an opt-in require (#2415)
+* ADDED: Move the global logger provider behind an opt-in require (#2415)
+
+### v0.5.0 / 2026-09-15
+
+* BREAKING CHANGE: Align LoggerProvider#logger with the SDK signature (#2375)
+* FIXED: Align LoggerProvider#logger with the SDK signature (#2375)
+* FIXED: Forward on_emit arguments to the delegate logger (#2376)
+
 ### v0.4.1 / 2026-07-08
 
 * DOCS: Update source for gemspec links to RubyDoc (#2123)

data/README.md

@@ -0,0 +1,80 @@
+# opentelemetry-logs-api
+
+The `opentelemetry-logs-api` gem is an alpha implementation of the [OpenTelemetry Logs API][logs-api] for Ruby applications. When opentelemetry-logs-api is installed, instrumentation can use OpenTelemetry API methods to emit log records.
+
+## What is OpenTelemetry?
+
+[OpenTelemetry][opentelemetry-home] is an open source observability framework, providing a general-purpose API, SDK, and related tools required for the instrumentation of cloud-native software, frameworks, and libraries.
+
+OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces, metrics, and logs from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.
+
+## How does this gem fit in?
+
+The `opentelemetry-logs-api` gem defines the core OpenTelemetry interfaces in the form of abstract classes and no-op implementations. That is, it defines interfaces and data types sufficient for instrumentation to code against to produce log records, but does not actually collect, process, or export the data.
+
+To collect and export log records, _applications_ should also install a concrete implementation of the API, such as the `opentelemetry-logs-sdk` gem.
+
+This code is still under development and is not a complete implementation of the Logs API. Until the code becomes stable, Logs API functionality will live outside the `opentelemetry-api` library.
+
+## How do I get started?
+
+Install the gems using:
+
+```sh
+gem install opentelemetry-sdk
+gem install opentelemetry-logs-sdk
+```
+
+Or, if you use [bundler][bundler-home], include `opentelemetry-sdk` and `opentelemetry-logs-sdk` in your `Gemfile`. The SDK depends on `opentelemetry-logs-api`.
+
+Requiring `opentelemetry-logs-sdk` defines the global `OpenTelemetry.logger_provider` accessor. Requiring `opentelemetry-logs-api` on its own does not. See [Upgrading to 0.6.0](#upgrading-to-060).
+
+```ruby
+require 'opentelemetry/sdk'
+require 'opentelemetry-logs-sdk'
+
+OpenTelemetry::SDK.configure
+
+# Obtain a logger from the global logger provider.
+logger = OpenTelemetry.logger_provider.logger(name: 'my_app', version: '1.0')
+
+# Emit a log record.
+logger.on_emit(severity_text: 'INFO', body: 'Hello, world!')
+```
+
+For additional examples, see the [examples on github][examples-github].
+
+## Upgrading to 0.6.0
+
+The Logs API is experimental. To keep it off the public `OpenTelemetry` module until it stabilizes, `opentelemetry-logs-api` 0.6.0 no longer defines `OpenTelemetry.logger_provider` or `OpenTelemetry.logger_provider=`. `opentelemetry-logs-sdk` 0.8.0 and later define both when required.
+
+- **Applications using `opentelemetry-logs-sdk`:** Upgrade the SDK to 0.8.0 or later. No code changes are needed.
+- **Code that requires only `opentelemetry-logs-api`:** Calling `OpenTelemetry.logger_provider` raises `NoMethodError`. Require `opentelemetry-logs-sdk`, or `opentelemetry/logs/global` to define the accessors without the SDK.
+- **Applications on `opentelemetry-logs-sdk` 0.7.0 or earlier:** These versions allow `opentelemetry-logs-api` 0.6.0, so bundler can pair them. A compatibility shim in the API keeps them working and logs this warning:
+
+  ```text
+  opentelemetry-logs-sdk 0.7.0 and earlier register the global logger provider through a compatibility shim in opentelemetry-logs-api. Upgrade to opentelemetry-logs-sdk 0.8.0 or later.
+  ```
+
+  The shim will be removed in a future release ([#2414][2414]). Upgrade the SDK to clear the warning.
+
+## How can I get involved?
+
+The `opentelemetry-logs-api` gem source is [on github][repo-github], along with related gems including `opentelemetry-logs-sdk`.
+
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us in [GitHub Discussions][discussions-url] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+
+## License
+
+The `opentelemetry-logs-api` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information.
+
+[logs-api]: https://opentelemetry.io/docs/specs/otel/logs/api/
+[opentelemetry-home]: https://opentelemetry.io
+[bundler-home]: https://bundler.io
+[repo-github]: https://github.com/open-telemetry/opentelemetry-ruby
+[license-github]: https://github.com/open-telemetry/opentelemetry-ruby/blob/main/LICENSE
+[examples-github]: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/examples/logs_sdk
+[ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
+[community-meetings]: https://github.com/open-telemetry/community#community-meetings
+[discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions
+[2414]: https://github.com/open-telemetry/opentelemetry-ruby/issues/2414

data/lib/opentelemetry/internal/global_logger_provider.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  # @api private
+  module Internal
+    @logger_provider = ProxyLoggerProvider.new
+    @logger_provider_mutex = Mutex.new
+
+    class << self
+      # Registers the process-wide logger provider that instrumentation reads
+      # from. The public +OpenTelemetry.logger_provider+ accessor, defined in
+      # +opentelemetry/logs/global+, delegates here.
+      #
+      # @param [LoggerProvider] provider A logger provider to register as the
+      #   global instance.
+      def logger_provider=(provider)
+        @logger_provider_mutex.synchronize do
+          if @logger_provider.instance_of?(ProxyLoggerProvider)
+            OpenTelemetry.logger.debug("Upgrading default proxy logger provider to #{provider.class}")
+            @logger_provider.delegate = provider
+          end
+          @logger_provider = provider
+        end
+      end
+
+      # @return [Object, Logs::LoggerProvider] registered logger provider or a
+      #   default no-op implementation of the logger provider.
+      def logger_provider
+        @logger_provider_mutex.synchronize { @logger_provider }
+      end
+    end
+  end
+end

data/lib/opentelemetry/internal/proxy_logger.rb

@@ -22,6 +22,8 @@ module OpenTelemetry
         @delegate = nil
       end
 
+      # Emits a {LogRecord} through the delegate logger, or discards it while
+      # no delegate is installed. See {OpenTelemetry::Logs::Logger#on_emit}.
       def on_emit(
         timestamp: nil,
         observed_timestamp: nil,
@@ -37,17 +39,17 @@ module OpenTelemetry
       )
         unless @delegate.nil?
           return @delegate.on_emit(
-            timestamp: nil,
-            observed_timestamp: nil,
-            severity_number: nil,
-            severity_text: nil,
-            body: nil,
-            trace_id: nil,
-            span_id: nil,
-            trace_flags: nil,
-            attributes: nil,
-            event_name: nil,
-            context: nil
+            timestamp: timestamp,
+            observed_timestamp: observed_timestamp,
+            severity_number: severity_number,
+            severity_text: severity_text,
+            body: body,
+            trace_id: trace_id,
+            span_id: span_id,
+            trace_flags: trace_flags,
+            attributes: attributes,
+            event_name: event_name,
+            context: context
           )
         end
 

data/lib/opentelemetry/internal/proxy_logger_provider.rb

@@ -38,19 +38,19 @@ module OpenTelemetry
 
         @mutex.synchronize do
           @delegate = provider
-          @registry.each { |key, logger| logger.delegate = provider.logger(key.name, key.version) }
+          @registry.each { |key, logger| logger.delegate = provider.logger(name: key.name, version: key.version) }
         end
       end
 
       # Returns a {Logger} instance.
       #
-      # @param [optional String] name Instrumentation package name
-      # @param [optional String] version Instrumentation package version
+      # @param [String] name Instrumentation scope name
+      # @param [optional String] version Instrumentation scope version
       #
       # @return [Logger]
-      def logger(name = nil, version = nil)
+      def logger(name:, version: nil)
         @mutex.synchronize do
-          return @delegate.logger(name, version) unless @delegate.nil?
+          return @delegate.logger(name: name, version: version) unless @delegate.nil?
 
           @registry[Key.new(name, version)] ||= ProxyLogger.new
         end

data/lib/opentelemetry/logs/global.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry-logs-api'
+
+# Defines the top-level accessors for the global logger provider. The Logs
+# API is unstable, so requiring +opentelemetry-logs-api+ does not define
+# these. Requiring +opentelemetry-logs-sdk+ does.
+#
+# These are delegators. The provider itself lives in
+# {OpenTelemetry::Internal}, so this file can be required at any point,
+# before or after the SDK is configured.
+module OpenTelemetry
+  # Register the global logger provider.
+  #
+  # @param [LoggerProvider] provider A logger provider to register as the
+  #   global instance.
+  def logger_provider=(provider)
+    Internal.logger_provider = provider
+  end
+
+  # @return [Object, Logs::LoggerProvider] registered logger provider or a
+  #   default no-op implementation of the logger provider.
+  def logger_provider
+    Internal.logger_provider
+  end
+end

data/lib/opentelemetry/logs/legacy_global_compat.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Installs the top-level logger provider accessors on behalf of logs SDKs
+# released before those accessors moved out of this gem. Those versions assign
+# and read +OpenTelemetry.logger_provider+ while configuring, and have no way
+# to require +opentelemetry/logs/global+ themselves.
+#
+# Such an SDK is always loaded by the time it reaches for the accessor, so the
+# check cannot happen at require time. It happens on the miss instead.
+#
+# Removal is tracked in #2414.
+module OpenTelemetry
+  module Logs
+    # Detects a logs SDK that predates {OpenTelemetry::Logs::Global} and
+    # installs the accessors it expects. With no SDK loaded, +super+ raises
+    # NoMethodError, which is what a caller holding only the API is meant to
+    # get.
+    #
+    # @api private
+    module LegacyGlobalCompat
+      ACCESSORS = %i[logger_provider logger_provider=].freeze
+
+      WARNING = 'opentelemetry-logs-sdk 0.7.0 and earlier register the global logger ' \
+                'provider through a compatibility shim in opentelemetry-logs-api. ' \
+                'Upgrade to opentelemetry-logs-sdk 0.8.0 or later.'
+
+      # Keyed on LoggerProvider rather than the SDK's Logs namespace, which
+      # another gem could plausibly define without the SDK being present.
+      def self.handles?(name)
+        ACCESSORS.include?(name) && defined?(OpenTelemetry::SDK::Logs::LoggerProvider)
+      end
+
+      private
+
+      def method_missing(name, *, &)
+        return super unless LegacyGlobalCompat.handles?(name)
+
+        require 'opentelemetry/logs/global'
+        return super unless singleton_class.method_defined?(name)
+
+        OpenTelemetry.logger.warn(WARNING)
+        public_send(name, *, &)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        LegacyGlobalCompat.handles?(name) || super
+      end
+    end
+  end
+
+  singleton_class.prepend(Logs::LegacyGlobalCompat)
+end

data/lib/opentelemetry/logs/logger_provider.rb

@@ -13,11 +13,11 @@ module OpenTelemetry
 
       # Returns an {OpenTelemetry::Logs::Logger} instance.
       #
-      # @param [optional String] name Instrumentation package name
-      # @param [optional String] version Instrumentation package version
+      # @param [String] name Instrumentation scope name
+      # @param [optional String] version Instrumentation scope version
       #
       # @return [OpenTelemetry::Logs::Logger]
-      def logger(name = nil, version = nil)
+      def logger(name:, version: nil)
         @logger ||= NOOP_LOGGER
       end
     end

data/lib/opentelemetry/logs/version.rb

@@ -7,6 +7,6 @@
 module OpenTelemetry
   module Logs
     ## Current OpenTelemetry logs version
-    VERSION = '0.4.1'
+    VERSION = '0.6.0'
   end
 end

data/lib/opentelemetry-logs-api.rb

@@ -9,33 +9,12 @@ require 'opentelemetry/logs'
 require 'opentelemetry/logs/version'
 require 'opentelemetry/internal/proxy_logger_provider'
 require 'opentelemetry/internal/proxy_logger'
+require 'opentelemetry/internal/global_logger_provider'
+require 'opentelemetry/logs/legacy_global_compat'
 
 # OpenTelemetry is an open source observability framework, providing a
 # general-purpose API, SDK, and related tools required for the instrumentation
 # of cloud-native software, frameworks, and libraries.
 #
-# The OpenTelemetry module in the Logs API gem provides global accessors
-# for logs-related objects.
-module OpenTelemetry
-  @logger_provider = Internal::ProxyLoggerProvider.new
-
-  # Register the global logger provider.
-  #
-  # @param [LoggerProvider] provider A logger provider to register as the
-  #   global instance.
-  def logger_provider=(provider)
-    @mutex.synchronize do
-      if @logger_provider.instance_of? Internal::ProxyLoggerProvider
-        logger.debug("Upgrading default proxy logger provider to #{provider.class}")
-        @logger_provider.delegate = provider
-      end
-      @logger_provider = provider
-    end
-  end
-
-  # @return [Object, Logs::LoggerProvider] registered logger provider or a
-  #   default no-op implementation of the logger provider.
-  def logger_provider
-    @mutex.synchronize { @logger_provider }
-  end
-end
+# Requiring this gem makes the Logs API available to instrumentation through
+# {OpenTelemetry::Internal.logger_provider}.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opentelemetry-logs-api
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - OpenTelemetry Authors
@@ -32,10 +32,14 @@ files:
 - ".yardopts"
 - CHANGELOG.md
 - LICENSE
+- README.md
 - lib/opentelemetry-logs-api.rb
+- lib/opentelemetry/internal/global_logger_provider.rb
 - lib/opentelemetry/internal/proxy_logger.rb
 - lib/opentelemetry/internal/proxy_logger_provider.rb
 - lib/opentelemetry/logs.rb
+- lib/opentelemetry/logs/global.rb
+- lib/opentelemetry/logs/legacy_global_compat.rb
 - lib/opentelemetry/logs/log_record.rb
 - lib/opentelemetry/logs/logger.rb
 - lib/opentelemetry/logs/logger_provider.rb
@@ -45,10 +49,10 @@ homepage: https://github.com/open-telemetry/opentelemetry-ruby
 licenses:
 - Apache-2.0
 metadata:
-  changelog_uri: https://rubydoc.info/gems/opentelemetry-logs-api/0.4.1/file/CHANGELOG.md
-  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-logs-api/v0.4.1/logs_api
+  changelog_uri: https://rubydoc.info/gems/opentelemetry-logs-api/0.6.0/file/CHANGELOG.md
+  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-logs-api/v0.6.0/logs_api
   bug_tracker_uri: https://github.com/open-telemetry/opentelemetry-ruby/issues
-  documentation_uri: https://rubydoc.info/gems/opentelemetry-logs-api/0.4.1
+  documentation_uri: https://rubydoc.info/gems/opentelemetry-logs-api/0.6.0
 rdoc_options: []
 require_paths:
 - lib
@@ -63,7 +67,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Logs API implementation for OpenTelemetry
 test_files: []