opentelemetry-logs-api 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bcc2cd3e4fc7a60b02c3986b19e954fde08dc1b53303e46e47810d8f72565dc
-  data.tar.gz: 43eca62177b7e61f20583df1ba6303f3fba0224a327d03f3968d94646a804a71
+  metadata.gz: 9b79311663b08bc24f42364c95dc9e9ad7661305c1133fc4055325812a875acd
+  data.tar.gz: 15ffffa097e04d769baafcdef433516ff1ee6da3e958e048b0b8594299e711a0
 SHA512:
-  metadata.gz: 685d355b9c779498d5759b5abdedad44351b50e277151fbef97986c176ad6343098b472c5705ce28d93a5f149f8cb5b1e4ade86c527f89fd8d66e5292542fdb9
-  data.tar.gz: 77ba825f6b8dff5bc65442547ab546ead001101d22add1d5b33d34ae686a31dd981b351f2fd5f161b18bc2fad7fb3e60ee91c3bcc5db6bbe25982fdf86b81f69
+  metadata.gz: 8189d762e8015fe69d8a892df36a85a87f49fd3b13ca567e62f1a0f8f9cfebd96010156c1f26c6d6e21c3d540eaf6c3535a06c08a1f0c73afb2ab36d54426145
+  data.tar.gz: 0bc233125c84872680eb184293616b22afd3be29262d001ac0502c8b8afeab06c308f172535fb4dd82694e4c06b2c1497f0ebfcf4a05fbcefc8fc264b995aa01

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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)

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/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/version.rb

@@ -7,6 +7,6 @@
 module OpenTelemetry
   module Logs
     ## Current OpenTelemetry logs version
-    VERSION = '0.5.0'
+    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.5.0
+  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.5.0/file/CHANGELOG.md
-  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-logs-api/v0.5.0/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.5.0
+  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.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Logs API implementation for OpenTelemetry
 test_files: []