launchdarkly-observability 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d46f86b88f2c7b3dfd876ef07b2135e8d11f8939c66a1071246ebb627b387f0d
-  data.tar.gz: 28d3c8ab27674a1e4ca3996c805d97136782198b2da0a96e8f64902d49ed1f4e
+  metadata.gz: cd8ffbd0f163139ada7ca0908969dbdc7f5b4b011c76e297bcf6c5c7c50cf438
+  data.tar.gz: 72ea24f86f9e22a0af99ee8ea84d175f29d9c8a9dc87451daaa31e770d5d111d
 SHA512:
-  metadata.gz: cd64fc216a9af53ec0c78bc4af429edf051e0da37b8568e4611d78bd0863711d2ca0b94fb8de97c39b30de4f0828c4eb2a874ce5148e0491f0ba320f716ad96f
-  data.tar.gz: 40114279e622a08632d68b63f5faebb4f77230cfe72f8a7a723b2a27898f81bf1c7a2179204068ebb3c178451339f8de7e0ca52840a77fe8d68c9e0721151663
+  metadata.gz: 42fe80077d434efa30061e01608781323ab215a36b49d1852326158025837ca04541605534c6d1ed52c707598795ba66889194bf3dac6f2f1aa8d8cc475ae1af
+  data.tar.gz: af53b3d86a7ad13b0f47b67a96ef14ae85706f7575c4b15fafe61524c0b1ec00b7ee9d9a8b986ee6ebd0790d50fe33c00cad07d49a1f21b98d06de7c52503708

data/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0](https://github.com/launchdarkly/observability-sdk/compare/launchdarkly-observability-ruby/0.2.2...launchdarkly-observability-ruby/0.3.0) (2026-06-29)
+
+
+### Features
+
+* **ruby:** boot-time OTel auto-instrumentation; keep it working on Rails 7.0 ([#643](https://github.com/launchdarkly/observability-sdk/issues/643)) ([350d549](https://github.com/launchdarkly/observability-sdk/commit/350d54994ff3745aba3d8f9a4c8602ce18dc6807))
+
 ## [0.2.2](https://github.com/launchdarkly/observability-sdk/compare/launchdarkly-observability-ruby/0.2.1...launchdarkly-observability-ruby/0.2.2) (2026-06-22)
 
 

data/README.md

@@ -38,13 +38,43 @@ The gem includes everything needed for traces and logs out of the box:
 - `launchdarkly-server-sdk` >= 8.11.0 (plugin support was added in 8.11.0)
 - `opentelemetry-sdk` ~> 1.4
 - `opentelemetry-exporter-otlp` ~> 0.28
-- `opentelemetry-instrumentation-all` ~> 0.62
 - `opentelemetry-logs-sdk` ~> 0.1
 - `opentelemetry-exporter-otlp-logs` ~> 0.1
+- A curated set of individual `opentelemetry-instrumentation-*` gems (see [Ruby & Rails compatibility](#ruby--rails-compatibility))
 
 For metrics support (optional):
 - `opentelemetry-metrics-sdk` ~> 0.1
 
+### Ruby & Rails compatibility
+
+| Component | Supported |
+|-----------|-----------|
+| Ruby      | >= 3.0 |
+| Rails     | >= 7.0 (auto-instrumentation); Rack / Sinatra / other Rack apps are unaffected by Rails version |
+
+The plugin depends on **individual** `opentelemetry-instrumentation-*` gems rather
+than the `opentelemetry-instrumentation-all` meta-gem. The meta-gem couples every
+instrumentation to a single version, so when the Rails-family instrumentations
+raised their minimum to Rails 7.1, Rails 7.0 apps silently lost *all*
+auto-instrumentation. Listing gems individually keeps the Rails family
+(`opentelemetry-instrumentation-rails`, `-action_pack`, `-active_record`,
+`-active_support`, `-action_view`, `-active_job`, `-action_mailer`,
+`-active_storage`) pinned below the releases that require Rails 7.1, while every
+other instrumentation tracks the latest version. Those pinned releases are still
+compatible with Rails 7.1+, so modern apps are unaffected.
+
+If an instrumentation cannot attach on your framework version, the plugin emits a
+**single actionable warning** (instead of a flurry of "failed to install" lines)
+and keeps everything else working — flag-eval spans, manual instrumentation, logs,
+and error capture are unaffected. You can add any other
+`opentelemetry-instrumentation-*` gem to your own Gemfile and it is picked up
+automatically (the plugin activates every instrumentation that is loaded), or pin
+one to a framework-compatible release, e.g.:
+
+```ruby
+gem 'opentelemetry-instrumentation-rails', '~> 0.41'
+```
+
 ## Quick Start
 
 ### Basic Usage (Non-Rails)
@@ -92,6 +122,15 @@ Rails.configuration.ld_client = LaunchDarkly::LDClient.new(
 at_exit { Rails.configuration.ld_client.close }
 ```
 
+> **Lazy client initialization:** Creating the LaunchDarkly client during boot
+> (as above) is recommended. If your app instead creates the client lazily —
+> e.g. from a model on first request, after Rails has finished booting — the gem
+> still installs the Rails auto-instrumentation during boot via its Railtie, as
+> long as `LAUNCHDARKLY_SDK_KEY` is set in the environment before Rails boots. If
+> it isn't, the OpenTelemetry Rails instrumentations can't attach (their load
+> hooks have already fired) and the plugin logs a single warning explaining how
+> to fix it.
+
 Use in controllers:
 
 ```ruby
@@ -145,10 +184,12 @@ LaunchDarklyObservability::Plugin.new(
   enable_logs: true,     # default: true
   enable_metrics: true,  # default: true
 
-  # Optional: Custom instrumentation configuration
+  # Optional: Custom instrumentation configuration. Keys are instrumentation
+  # class names; values are that instrumentation's own options (only pass
+  # options the installed instrumentation version supports).
   instrumentations: {
-    'OpenTelemetry::Instrumentation::Rails' => { enable_recognize_route: true },
-    'OpenTelemetry::Instrumentation::ActiveRecord' => { db_statement: :include }
+    'OpenTelemetry::Instrumentation::Rack' => { untraced_endpoints: ['/health'] },
+    'OpenTelemetry::Instrumentation::Net::HTTP' => { untraced_hosts: ['internal.example.com'] }
   }
 )
 ```
@@ -308,12 +349,17 @@ This generates:
 
 By default, the plugin enables OpenTelemetry auto-instrumentation for common Ruby libraries:
 
-- **Rails**: Request tracing, route recognition
-- **ActiveRecord**: Database query tracing
-- **Net::HTTP**: Outbound HTTP request tracing
+- **Rails** (and the Action/Active family): Request tracing, route recognition, DB queries, view rendering, jobs
+- **Net::HTTP**, **HTTP**, **Faraday**: Outbound HTTP request tracing
 - **Rack**: Request/response tracing
+- **PG**, **MySQL2**: Database query tracing
 - **Redis**: Cache operation tracing
 - **Sidekiq**: Background job tracing
+- **GraphQL**: Query/field tracing
+- **Sinatra**: Request tracing
+
+Need another library instrumented? Add its `opentelemetry-instrumentation-*` gem
+to your Gemfile — the plugin activates every loaded instrumentation automatically.
 
 ### Customizing Instrumentations
 

data/lib/launchdarkly-observability.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name (`launchdarkly-observability`) so that
+# Bundler.require auto-loads the gem during application boot. Without this,
+# Bundler's default `require 'launchdarkly-observability'` fails (the real entry
+# point is the underscore file) and users must require the gem manually — often
+# in an initializer, which is too late for the Rails Railtie to install
+# auto-instrumentation during boot.
+require_relative 'launchdarkly_observability'

data/lib/launchdarkly_observability/instrumentation_log_filter.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module LaunchDarklyObservability
+  # Wraps the OpenTelemetry logger to suppress the per-instrumentation install
+  # chatter ("... was successfully installed" / "... failed to install") and
+  # record the names of instrumentations that failed to install. Everything else
+  # (including level / level=) is delegated to the real logger.
+  #
+  # OpenTelemetryConfig uses this to replace the SDK's flurry of
+  # per-instrumentation warnings with a single actionable summary.
+  class InstrumentationLogFilter
+    FAILED_PATTERN = /Instrumentation: (\S+) failed to install/
+
+    # Run the block with OpenTelemetry.logger swapped for a filter that
+    # suppresses per-instrumentation install chatter, returning the names of any
+    # instrumentations that reported "failed to install". The SDK installs
+    # instrumentations after a configure block returns, so wrap the whole
+    # OpenTelemetry::SDK.configure call — not just use_all.
+    def self.capture_failures
+      original = OpenTelemetry.logger
+      failed = []
+      OpenTelemetry.logger = new(original, failed)
+      yield
+      failed
+    ensure
+      OpenTelemetry.logger = original
+    end
+
+    # Build ONE actionable warning naming the instrumentations that could not
+    # attach and how to resolve it. Telemetry that does not depend on those
+    # instrumentations (flag-eval spans, manual instrumentation, logs, errors)
+    # keeps working regardless.
+    def self.failure_warning(failed)
+      names = failed.map { |n| n.sub('OpenTelemetry::Instrumentation::', '') }.uniq
+      rails = defined?(::Rails) && ::Rails.respond_to?(:version) ? " on Rails #{::Rails.version}" : ''
+      "[LaunchDarklyObservability] #{names.size} OpenTelemetry instrumentation(s) could not attach" \
+        "#{rails} (Ruby #{RUBY_VERSION}): #{names.join(', ')}. Those libraries will not be " \
+        'auto-instrumented; flag-eval spans, manual instrumentation, logs and error capture are ' \
+        'unaffected. This usually means an instrumentation gem dropped support for your framework ' \
+        'version — upgrade the framework, or pin the instrumentation gem to a compatible release ' \
+        '(e.g. gem "opentelemetry-instrumentation-rails", "~> 0.41").'
+    end
+
+    def initialize(delegate, failed)
+      @delegate = delegate
+      @failed = failed
+    end
+
+    # OTel logs installs via OpenTelemetry.logger.info / .warn, so intercept the
+    # level methods (not just #add) — otherwise the calls fall through to
+    # method_missing and bypass the filter.
+    %i[debug info warn error fatal unknown].each do |level|
+      define_method(level) do |message = nil, &block|
+        forward?(message || block&.call) ? @delegate.public_send(level, message, &block) : true
+      end
+    end
+
+    def add(severity, message = nil, progname = nil, &block)
+      forward?(message || progname || block&.call) ? @delegate.add(severity, message, progname, &block) : true
+    end
+
+    def method_missing(name, ...)
+      @delegate.send(name, ...)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @delegate.respond_to?(name, include_private) || super
+    end
+
+    private
+
+    # Returns false when the message is install chatter that should be suppressed
+    # (recording failed-instrumentation names as a side effect), true when it
+    # should be forwarded to the real logger.
+    def forward?(message)
+      text = message.to_s
+      if (match = text.match(FAILED_PATTERN))
+        @failed << match[1]
+        return false
+      end
+
+      !text.include?('was successfully installed')
+    end
+  end
+end

data/lib/launchdarkly_observability/instrumentations.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Loads the OpenTelemetry auto-instrumentations the plugin enables by default.
+#
+# We require INDIVIDUAL instrumentation gems instead of
+# `opentelemetry/instrumentation/all` on purpose. The meta-gem couples every
+# instrumentation to a single version, so when the Rails-family instrumentations
+# raised their minimum to Rails 7.1 (opentelemetry-instrumentation-rails 0.42.0),
+# the whole bundle moved with them and Rails 7.0 apps silently lost ALL
+# auto-instrumentation. Requiring gems individually lets the Rails family stay on
+# a Rails-7.0-compatible release (pinned in the gemspec) while everything else
+# tracks the latest.
+#
+# `OpenTelemetry::SDK#use_all` activates every instrumentation that has been
+# loaded, so any additional `opentelemetry-instrumentation-*` gem a consumer adds
+# to their own Gemfile is picked up automatically alongside these defaults.
+
+# Rails family. Requiring this pulls every Rails-family instrumentation —
+# action_mailer, action_pack, action_view, active_job, active_record,
+# active_storage and active_support — which is why each is capped in the gemspec
+# (the Rails 7.0 floor has to hold on all of them, not just the rails meta-gem).
+# It also pulls concurrent_ruby, which tracks latest and is required explicitly
+# below.
+require 'opentelemetry/instrumentation/rails'
+
+# Common non-Rails instrumentations (latest; see gemspec for version policy).
+# Note the require paths differ from gem names in places, e.g. the
+# opentelemetry-instrumentation-net_http gem is required as 'net/http'.
+%w[
+  concurrent_ruby
+  faraday
+  graphql
+  http
+  mysql2
+  net/http
+  pg
+  rack
+  redis
+  sidekiq
+  sinatra
+].each do |path|
+  require "opentelemetry/instrumentation/#{path}"
+rescue LoadError => e
+  # A default instrumentation gem is unexpectedly absent. Don't abort the whole
+  # plugin over one missing instrumentation; the rest still load.
+  warn "[LaunchDarklyObservability] optional instrumentation '#{path}' not loaded: #{e.message}"
+end

data/lib/launchdarkly_observability/opentelemetry_config.rb

@@ -2,8 +2,9 @@
 
 require 'opentelemetry/sdk'
 require 'opentelemetry/exporter/otlp'
-require 'opentelemetry/instrumentation/all'
 require 'opentelemetry/semantic_conventions'
+require_relative 'instrumentations'
+require_relative 'instrumentation_log_filter'
 
 module LaunchDarklyObservability
   # Configures OpenTelemetry SDK with appropriate providers and exporters
@@ -61,6 +62,8 @@ module LaunchDarklyObservability
     def configure
       return if @configured
 
+      warn_ignored_boot_options if LaunchDarklyObservability.instrumentation_installed_at_boot?
+
       configure_traces if @options.fetch(:enable_traces, true)
       configure_logs if @options.fetch(:enable_logs, true)
       configure_metrics if @options.fetch(:enable_metrics, true)
@@ -70,6 +73,20 @@ module LaunchDarklyObservability
       @configured = true
     end
 
+    # Install the SDK tracer provider and auto-instrumentation WITHOUT exporters.
+    #
+    # Called from the Rails Railtie during boot so the Rails-family
+    # instrumentations (which patch via ActiveSupport.on_load hooks that fire
+    # during boot) attach even when the LaunchDarkly client — and therefore
+    # #register / #configure — is created lazily afterward. Exporters are added
+    # later by #configure_traces when the client registers the plugin.
+    def install_instrumentation_only
+      configure_sdk_capturing_failures do |c|
+        c.resource = create_resource
+        configure_instrumentations(c)
+      end
+    end
+
     # Flush all pending telemetry data
     def flush
       OpenTelemetry.tracer_provider&.force_flush
@@ -90,24 +107,93 @@ module LaunchDarklyObservability
 
     private
 
-    # Configure OpenTelemetry traces with OTLP exporter
+    # Configure OpenTelemetry traces with OTLP exporter.
+    #
+    # If auto-instrumentation was already installed during Rails boot (see
+    # LaunchDarklyObservability.install_rails_instrumentation), the SDK tracer
+    # provider already exists with instrumentation attached — so we add the OTLP
+    # span exporter and refresh its resource, rather than re-running
+    # OpenTelemetry::SDK.configure (which would replace the provider and, in the
+    # lazy-init case, drop the Rails-family instrumentation that can only attach
+    # during boot).
     def configure_traces
-      OpenTelemetry::SDK.configure do |c|
+      if LaunchDarklyObservability.instrumentation_installed_at_boot?
+        provider = OpenTelemetry.tracer_provider
+        provider.add_span_processor(create_batch_span_processor)
+
+        # The boot-time install built the provider's resource before this plugin
+        # (and its service_name/service_version options) existed, so it carries
+        # the inferred service name. configure_logs/configure_metrics below build
+        # a fresh resource from those options; without updating the trace
+        # resource too, spans would report a different service identity than logs
+        # and metrics. OTel exposes no resource setter, but the provider reads
+        # @resource live when creating each span — so update it in place.
+        provider.instance_variable_set(:@resource, create_resource)
+        return
+      end
+
+      configure_sdk_capturing_failures do |c|
         c.resource = create_resource
         c.add_span_processor(create_batch_span_processor)
 
         # Enable auto-instrumentation
         configure_instrumentations(c)
       end
+
+      warn_if_rails_instrumentation_missed
+    end
+
+    # Emit a single actionable warning when the plugin is registered after Rails
+    # has finished booting and boot-time instrumentation install did not run
+    # (e.g. LAUNCHDARKLY_SDK_KEY was not set in the environment at boot). In that
+    # case the OTel Rails-family instrumentations log a flurry of
+    # "failed to install" warnings because their load hooks have already fired.
+    def warn_if_rails_instrumentation_missed
+      return unless defined?(::Rails) && ::Rails.respond_to?(:application)
+      return unless ::Rails.application.respond_to?(:initialized?) && ::Rails.application.initialized?
+
+      warn '[LaunchDarklyObservability] The LaunchDarkly client was created after Rails finished ' \
+           'booting, so the Rails auto-instrumentation (ActionPack, ActiveRecord, ...) could not be ' \
+           'installed. To enable it, set LAUNCHDARKLY_SDK_KEY in the environment before Rails boots, ' \
+           'or create the LaunchDarkly client from a config/initializer.'
+    end
+
+    # Emit a single actionable warning when the client is created lazily (so
+    # instrumentation was installed at boot, before this plugin existed) but was
+    # given options that can only take effect at install time. Custom
+    # `instrumentations` config and `enable_traces: false` cannot be applied
+    # retroactively: an OTel instrumentation patches its library during boot via
+    # ActiveSupport.on_load hooks and cannot be reconfigured or detached
+    # afterward. (service_name/service_version are the exception — the trace
+    # resource is refreshed in #configure_traces because it is read live per
+    # span.) To honor these options, create the client from a config/initializer
+    # so #configure runs during boot with them.
+    def warn_ignored_boot_options
+      ignored = []
+      ignored << 'instrumentations' unless @options.fetch(:instrumentations, {}).empty?
+      ignored << 'enable_traces: false' unless @options.fetch(:enable_traces, true)
+      return if ignored.empty?
+
+      warn '[LaunchDarklyObservability] Rails auto-instrumentation was installed at boot, so these ' \
+           "plugin option(s) cannot be applied and will be ignored: #{ignored.join(', ')}. Instrumentations " \
+           'attach during boot, before the client exists, and cannot be reconfigured or detached afterward. ' \
+           'To apply these options, create the LaunchDarkly client from a config/initializer instead of lazily.'
     end
 
     # Configure auto-instrumentations with sensible defaults.
     # User-provided instrumentation config is merged on top of defaults,
     # so users only need to specify the instrumentations they want to override.
     def configure_instrumentations(config)
+      # Only pass options that the instrumentations actually accept. Unknown
+      # options are not fatal but emit a warning on every boot ("ignored the
+      # following unknown configuration options [...]"):
+      # - `enable_recognize_route` is not an option on the Rails, Rack, or
+      #   ActionPack instrumentations; route-based span naming (http.route) is
+      #   handled automatically by the ActionPack instrumentation.
+      # - ActiveRecord has no `db_statement` option; SQL capture comes from the
+      #   database adapter instrumentations (Mysql2, PG, ...) which default to
+      #   obfuscating statements.
       defaults = {
-        'OpenTelemetry::Instrumentation::Rails' => { enable_recognize_route: true },
-        'OpenTelemetry::Instrumentation::ActiveRecord' => { db_statement: :include },
         'OpenTelemetry::Instrumentation::Net::HTTP' => { untraced_hosts: [] },
         'OpenTelemetry::Instrumentation::Rack' => { untraced_endpoints: ['/health', '/healthz', '/ready'] }
       }
@@ -118,6 +204,20 @@ module LaunchDarklyObservability
       warn "[LaunchDarklyObservability] Error configuring instrumentations: #{e.message}"
     end
 
+    # Run an OpenTelemetry::SDK.configure block, replacing the SDK's
+    # per-instrumentation install logging (a flurry of "Instrumentation: <X>
+    # failed to install" WARN lines when instrumentations are incompatible with
+    # the framework version — e.g. the Rails family below its Rails floor) with a
+    # single actionable summary. The SDK installs the instrumentations AFTER the
+    # configure block returns (use_all only queues them), so the filter wraps the
+    # whole call, not just use_all.
+    def configure_sdk_capturing_failures(&block)
+      failed = InstrumentationLogFilter.capture_failures do
+        OpenTelemetry::SDK.configure(&block)
+      end
+      warn InstrumentationLogFilter.failure_warning(failed) unless failed.empty?
+    end
+
     # Configure OpenTelemetry logs with OTLP exporter.
     # The log gems are runtime dependencies, so require should always succeed.
     # If anything goes wrong, we warn once and leave traces unaffected.

data/lib/launchdarkly_observability/rails.rb

@@ -127,8 +127,22 @@ module LaunchDarklyObservability
           warn "[LaunchDarklyObservability] Could not attach log bridge to Rails.logger: #{e.message}"
         end
 
+        # The availability check is inlined here rather than delegating to
+        # LaunchDarklyObservability.otel_logger_provider_available? on purpose.
+        # rails.rb is required from launchdarkly_observability.rb *before* that
+        # file's `class << self` block (which defines the module method) has run.
+        # When the gem is lazily required after Rails has booted, the
+        # `config.after_initialize` hook above executes synchronously while this
+        # file is still loading, so the module method does not exist yet and the
+        # delegation raised "undefined method `otel_logger_provider_available?'".
         def otel_logger_provider_available?
-          LaunchDarklyObservability.send(:otel_logger_provider_available?)
+          # `defined?` returns nil (not false) when the constant is absent, so
+          # guard first and return an explicit boolean — callers (and the
+          # railtie test) expect true/false, never nil.
+          return false unless defined?(OpenTelemetry::SDK::Logs::LoggerProvider)
+
+          OpenTelemetry.respond_to?(:logger_provider) &&
+            OpenTelemetry.logger_provider.is_a?(OpenTelemetry::SDK::Logs::LoggerProvider)
         end
       end
 
@@ -136,6 +150,20 @@ module LaunchDarklyObservability
         app.middleware.insert_before(0, LaunchDarklyObservability::Middleware)
       end
 
+      # Install OpenTelemetry auto-instrumentation during boot so the Rails-family
+      # instrumentations attach even when the LaunchDarkly client is created
+      # lazily (after boot) rather than in an initializer.
+      #
+      # Runs `after: :load_config_initializers` on purpose: if the client was
+      # created in a config/initializer during boot, it has already configured
+      # OpenTelemetry (with the user's options), so `install_rails_instrumentation`
+      # detects the existing provider and no-ops. Otherwise it installs the
+      # default instrumentation now — still during boot, before eager loading and
+      # the ActiveSupport.on_load hooks that the instrumentations depend on.
+      initializer 'launchdarkly_observability.install_instrumentation', after: :load_config_initializers do
+        LaunchDarklyObservability.install_rails_instrumentation
+      end
+
       config.after_initialize do
         if defined?(ActionController::Base)
           ActionController::Base.include(LaunchDarklyObservability::ControllerHelpers)

data/lib/launchdarkly_observability/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LaunchDarklyObservability
-  VERSION = '0.2.2' # x-release-please-version
+  VERSION = '0.3.0' # x-release-please-version
 end

data/lib/launchdarkly_observability.rb

@@ -2,9 +2,13 @@
 
 require 'opentelemetry/sdk'
 require 'opentelemetry/exporter/otlp'
-require 'opentelemetry/instrumentation/all'
 require 'opentelemetry/semantic_conventions'
 
+# Loads the individual OpenTelemetry instrumentation gems (not the
+# opentelemetry-instrumentation-all meta-gem) so the Rails family can be pinned
+# for old-Rails compatibility independently of everything else.
+require_relative 'launchdarkly_observability/instrumentations'
+
 require_relative 'launchdarkly_observability/version'
 require_relative 'launchdarkly_observability/hook'
 require_relative 'launchdarkly_observability/opentelemetry_config'
@@ -13,7 +17,13 @@ require_relative 'launchdarkly_observability/source_context'
 
 require_relative 'launchdarkly_observability/middleware'
 require_relative 'launchdarkly_observability/otel_log_bridge'
-require_relative 'launchdarkly_observability/rails'
+
+# NOTE: rails.rb is required at the *bottom* of this file, after the
+# LaunchDarklyObservability module body has been fully defined. Its Railtie
+# registers a `config.after_initialize` hook that runs synchronously when the
+# gem is required lazily after Rails has booted. That hook references module
+# constants and `class << self` methods, so they must already exist when the
+# require runs. See the require at the end of this file.
 
 module LaunchDarklyObservability
   # Default OTLP endpoint for LaunchDarkly Observability
@@ -170,6 +180,60 @@ module LaunchDarklyObservability
       @instance = nil
     end
 
+    # @return [Boolean] whether auto-instrumentation was installed during Rails
+    #   boot by {.install_rails_instrumentation}. When true, the plugin attaches
+    #   exporters to the existing tracer provider at register time instead of
+    #   reconfiguring it.
+    def instrumentation_installed_at_boot?
+      @instrumentation_installed_at_boot == true
+    end
+
+    # Install OpenTelemetry auto-instrumentation during Rails boot.
+    #
+    # The OTel Rails-family instrumentations (ActionPack, ActiveRecord, ...) patch
+    # via ActiveSupport.on_load hooks that fire while Rails is booting. If the
+    # LaunchDarkly client is created lazily (e.g. from a model on first request),
+    # the plugin's #register runs after those hooks have fired and the
+    # instrumentations report "failed to install". The Rails Railtie calls this
+    # during boot so instrumentation attaches regardless of when the client is
+    # created. Exporters are still configured later, when the client registers
+    # the plugin.
+    #
+    # The project_id needed for the resource is resolved from the
+    # LAUNCHDARKLY_SDK_KEY environment variable, which is present at boot in the
+    # common case even when the client object is created lazily. If it cannot be
+    # resolved, instrumentation is left to #register (which warns if it then runs
+    # after boot).
+    #
+    # @param project_id [String, nil] explicit project id; falls back to ENV
+    # @param otlp_endpoint [String] OTLP endpoint (only relevant for exporters)
+    # @param options [Hash] additional OpenTelemetryConfig options
+    # @return [Boolean] whether instrumentation was installed
+    def install_rails_instrumentation(project_id: nil, otlp_endpoint: DEFAULT_ENDPOINT, **options)
+      return false if @instrumentation_installed_at_boot
+
+      project_id ||= ENV.fetch('LAUNCHDARKLY_SDK_KEY', nil)
+      return false if project_id.nil? || project_id.empty?
+
+      # If something already configured an SDK tracer provider (e.g. the client
+      # was created in a config/initializer during boot), don't reconfigure —
+      # that would replace the provider and drop its exporters.
+      return false if OpenTelemetry.tracer_provider.is_a?(OpenTelemetry::SDK::Trace::TracerProvider)
+
+      OpenTelemetryConfig.new(project_id: project_id, otlp_endpoint: otlp_endpoint, **options)
+                         .install_instrumentation_only
+      @instrumentation_installed_at_boot = true
+    rescue StandardError => e
+      warn "[LaunchDarklyObservability] Could not install Rails auto-instrumentation at boot: #{e.message}"
+      false
+    end
+
+    # Reset boot-instrumentation state. Intended for tests only.
+    # @api private
+    def reset_instrumentation_state!
+      @instrumentation_installed_at_boot = false
+    end
+
     private
 
     def otel_logger_provider_available?
@@ -179,3 +243,9 @@ module LaunchDarklyObservability
     end
   end
 end
+
+# Required last, on purpose: the Rails Railtie's `config.after_initialize` hook
+# can run synchronously during this require (lazy require after Rails has
+# booted), and it depends on the fully-defined LaunchDarklyObservability module
+# above. See the note next to the other require_relative calls at the top.
+require_relative 'launchdarkly_observability/rails'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: launchdarkly-observability
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.0
 platform: ruby
 authors:
 - LaunchDarkly
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-22 00:00:00.000000000 Z
+date: 2026-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: launchdarkly-server-sdk
@@ -39,33 +39,291 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.28'
 - !ruby/object:Gem::Dependency
-  name: opentelemetry-instrumentation-all
+  name: opentelemetry-sdk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.62'
+        version: '1.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.62'
+        version: '1.4'
 - !ruby/object:Gem::Dependency
-  name: opentelemetry-sdk
+  name: opentelemetry-instrumentation-action_mailer
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '0.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-action_pack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-action_view
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-active_job
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-active_record
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.13'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-active_storage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-active_support
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.34'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.42'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.34'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.42'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-concurrent_ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.24'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-graphql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.28'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.28'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.23'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.23'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-mysql2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.28'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.28'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-net_http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.29'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.29'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.24'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.25'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-sidekiq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.25'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.24'
 - !ruby/object:Gem::Dependency
   name: opentelemetry-semantic_conventions
   requirement: !ruby/object:Gem::Requirement
@@ -161,8 +419,11 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- lib/launchdarkly-observability.rb
 - lib/launchdarkly_observability.rb
 - lib/launchdarkly_observability/hook.rb
+- lib/launchdarkly_observability/instrumentation_log_filter.rb
+- lib/launchdarkly_observability/instrumentations.rb
 - lib/launchdarkly_observability/middleware.rb
 - lib/launchdarkly_observability/opentelemetry_config.rb
 - lib/launchdarkly_observability/otel_log_bridge.rb