rails-otel-context 0.9.4 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2e72559008d91dce5419a16fd46e12cf3e9f40f1d5767458e2c4f1a4bf15b2c
-  data.tar.gz: 86e841a066551ed02d85c15f0af9276c394de50586d70d07bc1cb588b2e33de4
+  metadata.gz: 6e06fe4be3a8bd4949ad32d7fbe9e3dac1090d9044b997c7427feee131776564
+  data.tar.gz: 61e3bc83de1debb6c9cafce615a8c7328b751bdbfb2ffa5bdf037cbae1a01a86
 SHA512:
-  metadata.gz: 7326aaca0ef8d0db842513355e10002deedc16cafa5823c39a8dfaf983a05e794482cea8cf371fcac2b42c7f52861e1c1b104ae97f0c3a2ffcbbc0107d8eb6e4
-  data.tar.gz: b4621bcc0dedd6d721268ed1f738f482335ab7953b45d8957655e62b046a5da1322cb76f40e1acbab20e2605dad17b06178f210067ce4dd3c3f1905b533f69b7
+  metadata.gz: 9424d03a617834466c9f52d7fb870f1a5dfdbd39c7966cf128c5df1bd87a497af38baff4be7838a9181f9e3c23e1659299c15b27d01d22d9af295c3cbbe4b4d3
+  data.tar.gz: 6201a8a0974a549ca93e3587d0fd416f57cc92c3594922d6e72685b9641477d2800ccf2e9b7c5d72d1504bbf877c8a3c47949e272cfbd647a3b697a61de7eaf1

data/README.md

@@ -118,6 +118,37 @@ RailsOtelContext.configure do |c|
 end
 ```
 
+## Conditional loading (`require: false`)
+
+If your Gemfile has `require: false` and you load the gem from an initializer, call `RailsOtelContext.install!` explicitly. Loading the gem inside `config/initializers/` is too late for Rails to run the railtie's initializer hooks, so without an explicit `install!` call the AR subscriber and `around_action` hooks are never registered — `code.activerecord.*` and `rails.controller` will be absent from all spans.
+
+```ruby
+# Gemfile
+gem 'rails-otel-context', '~> 0.9', require: false
+
+# config/initializers/opentelemetry.rb
+return unless ENV['ENABLE_OTLP']
+
+require 'rails_otel_context'
+
+RailsOtelContext.configure do |c|
+  c.span_name_formatter = lambda { |original, ar| ... }
+end
+
+RailsOtelContext.install! # registers AR hooks, around_action, and the span processor
+
+require 'opentelemetry/sdk'
+require 'opentelemetry/exporter/otlp'
+require 'opentelemetry/instrumentation/all'
+
+OpenTelemetry::SDK.configure do |c|
+  c.service_name = ENV.fetch('OTEL_SERVICE_NAME', 'my_app')
+  c.use_all
+end
+```
+
+`install!` is idempotent — the railtie calls it automatically via `after_initialize`, so apps that let Bundler auto-require the gem do not need to call it.
+
 ## How `code.namespace` / `code.function` works
 
 On every span start, the gem walks the Ruby call stack (`Thread.each_caller_location`) and finds the first frame inside `Rails.root`. That frame becomes the four `code.*` attributes.

data/lib/rails_otel_context/call_context_processor.rb

@@ -71,9 +71,11 @@ module RailsOtelContext
       nil
     end
 
-    def force_flush(timeout: nil); end
-
-    def shutdown(timeout: nil); end
+    # Return Export::SUCCESS (0) so the SDK's tracer_provider.force_flush/shutdown
+    # can safely call results.max across all registered processors without raising
+    # ArgumentError when mixing our return value with integer status codes.
+    def force_flush(**) = 0
+    def shutdown(**) = 0
 
     private
 

data/lib/rails_otel_context/railtie.rb

@@ -5,23 +5,12 @@ require 'rails_otel_context/call_context_processor'
 
 module RailsOtelContext
   class Railtie < Rails::Railtie
-    initializer 'rails_otel_context.install_adapters' do
-      ActiveSupport.on_load(:active_record) do
-        RailsOtelContext::Adapters.install!(app_root: Rails.root, config: RailsOtelContext.configuration)
-        RailsOtelContext::ActiveRecordContext.install!(app_root: Rails.root)
-      end
-    end
-
-    # Runs after config/initializers/ so the OTel SDK tracer_provider is already configured.
+    # Runs after config/initializers/ so the OTel SDK tracer_provider is already
+    # configured. install! is idempotent — if the app already called
+    # RailsOtelContext.install! from an initializer this is a no-op for hooks,
+    # but install_processor! still runs (it self-guards with @processor_installed).
     config.after_initialize do
-      RailsOtelContext.install_processor!
-
-      # Warm the table→model map once at boot (after eager_load! in production so
-      # all descendants are available). Without this, the first SQL-named span on a
-      # cold boot hits an empty map and falls through without model context.
-      ActiveSupport.on_load(:active_record) do
-        RailsOtelContext::ActiveRecordContext.ar_table_model_map
-      end
+      RailsOtelContext.install!
     end
 
     # Reset the table→model map after every code reload in development.
@@ -31,43 +20,5 @@ module RailsOtelContext
     config.to_prepare do
       RailsOtelContext::ActiveRecordContext.reset_ar_table_model_map!
     end
-
-    # Capture controller + action for every request and propagate them to all
-    # child spans via RequestContext. Also resets the N+1 query counter at both
-    # the start and end of every request to prevent bleed across Puma thread reuse.
-    # Always-on — no config gate.
-    #
-    # Both hooks are required: ActionController::Base fires :action_controller,
-    # ActionController::API (Rails API-only apps) fires :action_controller_api.
-    # In Rails 8 API-only apps :action_controller never fires, so without the
-    # second hook rails.controller / rails.action would be absent from every span.
-    initializer 'rails_otel_context.install_request_context' do
-      around_action_hook = proc do
-        around_action do |_controller, block|
-          RailsOtelContext::RequestContext.set(
-            controller: self.class.name,
-            action: action_name
-          )
-          block.call
-        ensure
-          RailsOtelContext::RequestContext.clear!
-        end
-      end
-      ActiveSupport.on_load(:action_controller, &around_action_hook)
-      ActiveSupport.on_load(:action_controller_api, &around_action_hook)
-    end
-
-    # Capture job class name for every ActiveJob execution and propagate it to all
-    # child spans via RequestContext so rails.job appears on every span in the job.
-    initializer 'rails_otel_context.install_job_context' do
-      ActiveSupport.on_load(:active_job) do
-        around_perform do |_job, block|
-          RailsOtelContext::RequestContext.set_job(job_class: self.class.name)
-          block.call
-        ensure
-          RailsOtelContext::RequestContext.clear_job!
-        end
-      end
-    end
   end
 end

data/lib/rails_otel_context/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsOtelContext
-  VERSION = '0.9.4'
+  VERSION = '0.9.6'
 end

data/lib/rails_otel_context.rb

@@ -30,13 +30,32 @@ module RailsOtelContext
       @configuration = Configuration.new
     end
 
+    # Full installation: registers all Rails hooks (AR adapters, around_action,
+    # around_perform) and the CallContextProcessor. Safe to call from a
+    # config/initializers file when the gem is loaded with require: false:
+    #
+    #   # config/initializers/opentelemetry.rb
+    #   return unless ENV['ENABLE_OTLP']
+    #   require 'rails_otel_context'
+    #   RailsOtelContext.configure { |c| ... }
+    #   RailsOtelContext.install!
+    #
+    # The Railtie calls this automatically via after_initialize, so apps that
+    # let Bundler auto-require the gem do not need to call it explicitly.
+    # Safe to call multiple times — idempotent.
+    def install!(app_root: nil)
+      app_root ||= Rails.root if defined?(Rails)
+      register_hooks!(app_root) unless @hooks_installed
+      install_processor!
+    end
+
     # Registers CallContextProcessor with the OTel tracer_provider.
-    # Called automatically by the Railtie after_initialize. Call this manually
-    # when OpenTelemetry::SDK.configure runs after Rails boot (e.g. in a custom
-    # after_initialize block):
+    # Called automatically by install!. Call this manually only when the OTel
+    # SDK is configured after install! has already run (rare):
     #
-    #   OpenTelemetry::SDK.configure { |c| c.use_all() }
-    #   RailsOtelContext.install_processor!
+    #   RailsOtelContext.install!          # hooks up AR/request context
+    #   OpenTelemetry::SDK.configure { … } # SDK configured later
+    #   RailsOtelContext.install_processor! # add processor to the now-real provider
     #
     # Safe to call multiple times — idempotent.
     def install_processor!
@@ -49,6 +68,43 @@ module RailsOtelContext
       OpenTelemetry.tracer_provider.add_span_processor(processor)
     end
 
+    private
+
+    def register_hooks!(app_root)
+      @hooks_installed = true
+
+      ActiveSupport.on_load(:active_record) do
+        RailsOtelContext::Adapters.install!(app_root: app_root, config: RailsOtelContext.configuration)
+        RailsOtelContext::ActiveRecordContext.install!(app_root: app_root)
+        RailsOtelContext::ActiveRecordContext.ar_table_model_map
+      end
+
+      around_action_hook = proc do
+        around_action do |_controller, block|
+          RailsOtelContext::RequestContext.set(
+            controller: self.class.name,
+            action: action_name
+          )
+          block.call
+        ensure
+          RailsOtelContext::RequestContext.clear!
+        end
+      end
+      ActiveSupport.on_load(:action_controller, &around_action_hook)
+      ActiveSupport.on_load(:action_controller_api, &around_action_hook)
+
+      ActiveSupport.on_load(:active_job) do
+        around_perform do |_job, block|
+          RailsOtelContext::RequestContext.set_job(job_class: self.class.name)
+          block.call
+        ensure
+          RailsOtelContext::RequestContext.clear_job!
+        end
+      end
+    end
+
+    public
+
     # Convenience delegates to FrameContext — see FrameContext for full docs.
     def with_frame(class_name:, method_name:, &block)
       FrameContext.with_frame(class_name: class_name, method_name: method_name, &block)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-otel-context
 version: !ruby/object:Gem::Version
-  version: 0.9.4
+  version: 0.9.6
 platform: ruby
 authors:
 - Last9