rails-otel-context 0.9.4 → 0.9.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2e72559008d91dce5419a16fd46e12cf3e9f40f1d5767458e2c4f1a4bf15b2c
-  data.tar.gz: 86e841a066551ed02d85c15f0af9276c394de50586d70d07bc1cb588b2e33de4
+  metadata.gz: f8ea9eb65d7e405bbd14a39889bbad983edbba5c4bdcce252157d426a2372bc6
+  data.tar.gz: c70ddac87d64c8359fe82fe142bda62e4968b3429ea6944796b475270310d1d7
 SHA512:
-  metadata.gz: 7326aaca0ef8d0db842513355e10002deedc16cafa5823c39a8dfaf983a05e794482cea8cf371fcac2b42c7f52861e1c1b104ae97f0c3a2ffcbbc0107d8eb6e4
-  data.tar.gz: b4621bcc0dedd6d721268ed1f738f482335ab7953b45d8957655e62b046a5da1322cb76f40e1acbab20e2605dad17b06178f210067ce4dd3c3f1905b533f69b7
+  metadata.gz: cfee7357103d1336be233b9b6724c1b6678117f7fcd3e57dda75ca473a3a608c8f511e7151db29cd9bce34627fcd8d0b482fcdb640812941c960385bf57acadd
+  data.tar.gz: 15888432fb759223a87cdf35f0dd9ae00c07ac59ef038b06bd49644968996b23fc910b0cca0f0912857bf8a4101ad9d005aa66596cef5b4a1e29de68a12486c8

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/adapters/mysql2.rb

@@ -32,12 +32,11 @@ module RailsOtelContext
             end
           end
 
-          # AR context and span renaming handled by CallContextProcessor.apply_db_context.
+          # Push call-site into FrameContext BEFORE super so the OTel child span
+          # created inside super picks it up via CallContextProcessor#on_start.
           %i[query prepare].each do |method_name|
             define_method(method_name) do |*args|
-              result = super(*args)
-              mod.apply_call_site_to_span(OpenTelemetry::Trace.current_span, mod.call_site_for_app)
-              result
+              mod.with_call_site_frame { super(*args) }
             end
           end
         end

data/lib/rails_otel_context/adapters/pg.rb

@@ -42,16 +42,14 @@ module RailsOtelContext
             end
           end
 
-          # AR context and span renaming handled by CallContextProcessor.apply_db_context.
+          # Push call-site into FrameContext BEFORE super so the OTel child span
+          # created inside super picks it up via CallContextProcessor#on_start.
           methods.each do |method_name|
             define_method(method_name) do |*args, &user_block|
-              # Capture before super: PG yields into a block so the original
-              # call stack is only visible here, not inside the result block.
-              site = mod.call_site_for_app
-
-              super(*args) do |result|
-                mod.apply_call_site_to_span(OpenTelemetry::Trace.current_span, site)
-                user_block ? user_block.call(result) : result
+              mod.with_call_site_frame do
+                super(*args) do |result|
+                  user_block ? user_block.call(result) : result
+                end
               end
             end
           end

data/lib/rails_otel_context/adapters/trilogy.rb

@@ -32,11 +32,10 @@ module RailsOtelContext
             end
           end
 
-          # AR context and span renaming handled by CallContextProcessor.apply_db_context.
+          # Push call-site into FrameContext BEFORE super so the OTel child span
+          # created inside super picks it up via CallContextProcessor#on_start.
           define_method(:query) do |sql|
-            result = super(sql)
-            mod.apply_call_site_to_span(OpenTelemetry::Trace.current_span, mod.call_site_for_app)
-            result
+            mod.with_call_site_frame { super(sql) }
           end
         end
 

data/lib/rails_otel_context/call_context_processor.rb

@@ -71,26 +71,29 @@ 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
 
     def apply_call_context(span)
       # Explicit override: app code called FrameContext.with_frame (or Frameable).
       # O(1) — no stack walk. Takes priority over automatic detection.
-      pushed = FrameContext.current
-      if pushed
-        span.set_attribute('code.namespace', pushed[:class_name])
-        span.set_attribute('code.function',  pushed[:method_name]) if pushed[:method_name]
-        return
-      end
+      # DB adapters push filepath/lineno too so the child span gets full call-site info.
+      site = FrameContext.current
+      unless site
+        # Default: walk the call stack to find the nearest app-code frame.
+        return unless Thread.respond_to?(:each_caller_location)
 
-      # Default: walk the call stack to find the nearest app-code frame.
-      return unless Thread.respond_to?(:each_caller_location)
+        site = call_site_for_app
+      end
+      set_call_site_attributes(span, site)
+    end
 
-      site = call_site_for_app
+    def set_call_site_attributes(span, site)
       return unless site
 
       span.set_attribute('code.namespace', site[:class_name])

data/lib/rails_otel_context/frame_context.rb

@@ -27,17 +27,19 @@ module RailsOtelContext
     class << self
       # Pushes +class_name+/+method_name+ for the duration of the block,
       # restoring whatever was pushed before (supports nesting).
-      def with_frame(class_name:, method_name:)
+      # Optional +filepath:+ and +lineno:+ are carried through to the span
+      # processor so DB adapter call-site info survives the span lifecycle.
+      def with_frame(class_name:, method_name:, filepath: nil, lineno: nil)
         prev = Thread.current[FRAME_KEY]
-        Thread.current[FRAME_KEY] = { class_name: class_name, method_name: method_name }.freeze
+        Thread.current[FRAME_KEY] = build_frame(class_name, method_name, filepath, lineno)
         yield
       ensure
         Thread.current[FRAME_KEY] = prev
       end
 
       # Manual push without a block. Caller must call +pop+ in an ensure.
-      def push(class_name:, method_name:)
-        Thread.current[FRAME_KEY] = { class_name: class_name, method_name: method_name }.freeze
+      def push(class_name:, method_name:, filepath: nil, lineno: nil)
+        Thread.current[FRAME_KEY] = build_frame(class_name, method_name, filepath, lineno)
       end
 
       # Clears the pushed frame. Pair with +push+ in an ensure block.
@@ -51,6 +53,15 @@ module RailsOtelContext
       end
 
       alias clear! pop
+
+      private
+
+      def build_frame(class_name, method_name, filepath, lineno)
+        frame = { class_name: class_name, method_name: method_name }
+        frame[:filepath] = filepath if filepath
+        frame[:lineno]   = lineno   if lineno
+        frame.freeze
+      end
     end
   end
 

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

@@ -46,6 +46,22 @@ module RailsOtelContext
       span.set_attribute('code.lineno',    site[:lineno]) if site[:lineno]
     end
 
+    # Wraps a block with the nearest app-code frame pushed into FrameContext.
+    # Used by DB adapters to make the call-site available to
+    # CallContextProcessor#on_start for the child span created inside the block.
+    # Uses with_frame (not push/pop) so nested frames are correctly restored.
+    def with_call_site_frame(&)
+      site = call_site_for_app
+      if site
+        FrameContext.with_frame(
+          class_name: site[:class_name], method_name: site[:method_name],
+          filepath: site[:filepath], lineno: site[:lineno], &
+        )
+      else
+        yield
+      end
+    end
+
     # Legacy helper kept for Redis and ClickHouse adapters that only need filepath + lineno.
     # Migrate those adapters to call_site_for_app + apply_call_site_to_span to remove this.
     def source_location_for_app

data/lib/rails_otel_context/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsOtelContext
-  VERSION = '0.9.4'
+  VERSION = '0.9.7'
 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.7
 platform: ruby
 authors:
 - Last9