rails-otel-context 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33a9fb2ab0db69a25d4430149aa144b5bb88fe17929f595930320aa6d2adb230
-  data.tar.gz: 6a8d7d881ffcc2c497223e8be0705409c58490086a6349ca27f07445a8e37b88
+  metadata.gz: f9939fbc8981d0be3075a1c3f7dcbda1c87a0b0d40a5dc9186ace04aa05ef3aa
+  data.tar.gz: 88a58856ae020819ec9c17e5027d1b24b3c5da1d4609d3c43b909fa1e88df979
 SHA512:
-  metadata.gz: ad5399d6b648e82b479d37be7cf822a9c3eaa02c90a95e78e027caa2bdd7074c45b24b00d5d155b092ba2c1852daff4b10a8fe3b1c574c555c351fadb9af5972
-  data.tar.gz: b53c74ebe800be5c48d86daa4ac90a4c50d8b56fc7f1a36bc36882eb3f1a33bc8fbe86e841144c1e8bad83b3248203cd7f84aec9bcf903a11568d8609c1422e3
+  metadata.gz: dc0385bb7df75a0e678dcf03e1b77fa6826427395504bea021e11282f4f1d9f67aadbae64f59cef0d971fe3a6ac2f3208c81d60ea8ef953e316f9196a2ad5c20
+  data.tar.gz: 468262bd9bf9b9df37705e0aab8d5f39b3610b5754407c4f6f1220594b297eba8f01b3538ddb6fa71ff5e037b4551f7bce97c30e9dac565b500b7c956fb79d54

data/README.md

@@ -91,6 +91,7 @@ end
 | `request.action` | `"index"` | Rails action (requires `request_context_enabled`) |
 | `db.query_count` | `47` | How many times this model+operation was queried in this request — appears only on the 2nd+ occurrence, which flags N+1 patterns |
 | `db.slow` | `true` | Set when query duration exceeds `slow_query_threshold_ms` |
+| `db.async` | `true` | Set when query was issued via `load_async` (Rails 7.1+) |
 
 ## Span naming
 
@@ -102,9 +103,27 @@ Without a formatter, DB spans arrive named by the driver (`SELECT`, `INSERT`). T
 | `Transaction.total_revenue` | `code_function: "total_revenue"` | `Transaction.total_revenue` |
 | `Transaction.where(...).first` | `method_name: "Load"` | `Transaction.Load` |
 | `record.update(...)` | `method_name: "Update"` | `Transaction.Update` |
+| Counter cache, `connection.execute` | SQL parsed → table mapped to model | `User.Update` |
 
 The original span name is preserved in `l9.orig.name` so you can always filter on the raw driver operation.
 
+### Counter caches and raw SQL
+
+Rails counter caches, `touch_later`, and `connection.execute` calls fire `sql.active_record` with `payload[:name] = "SQL"` rather than `"User Update"`. The gem parses the SQL statement directly and maps the table name back to the AR model:
+
+```
+UPDATE `users` SET `users`.`comments_count` = COALESCE(...)
+  → code.activerecord.model: "User"
+  → code.activerecord.method: "Update"
+  → span renamed to "User.Update" (with formatter)
+```
+
+The table→model map is built from `AR::Base.descendants` on first use. In production with `eager_load!` this is always correct. In development, call this after a code reload if you see stale model names:
+
+```ruby
+RailsOtelContext::ActiveRecordContext.reset_ar_table_model_map!
+```
+
 ### Scope tracking
 
 The gem captures scope names from both the `scope` macro and plain class methods that return a relation:
@@ -131,6 +150,48 @@ c.redis_source_enabled = true
 
 No official OTel instrumentation exists for ClickHouse. This gem creates client spans automatically for `ClickHouse::Client`, `ClickHouse::Connection`, and `Clickhouse::Client`.
 
+## Benchmarks
+
+The subscriber runs in the hot path of every SQL query. Two scripts live in `bench/`:
+
+### Allocation guard (also runs in CI)
+
+Verifies the per-call allocation budget hasn't regressed. Deterministic — same count every run regardless of machine:
+
+```
+ruby bench/allocation_guard.rb
+```
+
+```
+PASS  named query (User Load): 4.0 allocs/call (budget: 4)
+PASS  SQL-named counter cache UPDATE: 6.0 allocs/call (budget: 6)
+
+All allocation budgets met.
+```
+
+Exits 1 if any path exceeds its budget. Update the budget constant in `bench/allocation_guard.rb` whenever a deliberate trade-off is made.
+
+### Full profiling suite
+
+Throughput, per-call allocations with top allocating lines, and a StackProf CPU flamegraph:
+
+```
+bundle exec ruby bench/subscriber_hot_path.rb
+```
+
+The flamegraph dump lands at `tmp/subscriber.dump`. View it with:
+
+```
+stackprof --flamegraph tmp/subscriber.dump | open -f -a 'Google Chrome'
+```
+
+**Baseline (Ruby 3.3, Apple M-series):**
+
+| Path | Allocs/call | Throughput |
+|---|---|---|
+| Named AR query (`User Load`) | 4 objects | ~900k i/s |
+| SQL counter cache (`name=SQL`) | 6 objects | ~650k i/s |
+
 ## Requirements
 
 - Ruby >= 3.1

data/lib/rails_otel_context/activerecord_context.rb

@@ -15,9 +15,29 @@ module RailsOtelContext
   module ActiveRecordContext
     THREAD_KEY        = :_rails_otel_ctx_ar
     SCOPE_THREAD_KEY  = :_rails_otel_ctx_scope
-    TIMING_THREAD_KEY = :_rails_otel_ctx_timing
+    TIMING_ID_KEY     = :_rails_otel_ctx_timing_id
+    TIMING_START_KEY  = :_rails_otel_ctx_timing_start
     DB_SLOW_ATTR      = 'db.slow'
-    private_constant :THREAD_KEY, :SCOPE_THREAD_KEY, :TIMING_THREAD_KEY
+    private_constant :THREAD_KEY, :SCOPE_THREAD_KEY, :TIMING_ID_KEY, :TIMING_START_KEY
+
+    # Frozen regex — only the verb regex remains; table extraction uses index+slice.
+    SQL_VERB_RE = /\A(\w+)/i
+    private_constant :SQL_VERB_RE
+
+    # Keywords for table extraction — frozen literals searched with index+slice.
+    # Rails-generated SQL uses uppercase keywords, covering counter caches and touch_later.
+    KW_UPDATE = 'UPDATE '
+    KW_INTO   = 'INTO '
+    KW_FROM   = 'FROM '
+    private_constant :KW_UPDATE, :KW_INTO, :KW_FROM
+
+    # Byte values used in extract_table_after for delimiter detection.
+    BYTE_BACKTICK = 96  # `
+    BYTE_DQUOTE   = 34  # "
+    BYTE_SQUOTE   = 39  # '
+    BYTE_SPACE    = 32  # (space)
+    BYTE_COMMA    = 44  # ,
+    private_constant :BYTE_BACKTICK, :BYTE_DQUOTE, :BYTE_SQUOTE, :BYTE_SPACE, :BYTE_COMMA
 
     # Tracks class methods (def self.name) that return an AR::Relation so their
     # name is captured as code.activerecord.scope, complementing ScopeNameTracking
@@ -68,23 +88,31 @@ module RailsOtelContext
       def start(_name, id, payload)
         ar_name = payload[:name]
         return unless ar_name
-        return if ar_name == 'SCHEMA' || ar_name.start_with?('CACHE') || ar_name == 'SQL'
+        return if ar_name == 'SCHEMA' || ar_name.start_with?('CACHE')
 
-        ctx = ActiveRecordContext.parse_ar_name(ar_name)
+        ctx = if ar_name == 'SQL'
+                ActiveRecordContext.parse_sql_context(payload[:sql])
+              else
+                ActiveRecordContext.parse_ar_name(ar_name)
+              end
         return unless ctx
 
         # Include scope name if one was captured by RelationScopeCapture
         scope = Thread.current[SCOPE_THREAD_KEY]
         ctx[:scope_name] = scope if scope
 
-        query_key = "#{ctx[:model_name]}.#{ctx[:method_name]}"
+        query_key = ctx[:query_key]
         counts = (Thread.current[RequestContext::QUERY_COUNT_KEY] ||= {})
         count = (counts[query_key] = (counts[query_key] || 0) + 1)
         ctx[:query_count] = count if count > 1
 
+        ctx[:async] = true if payload[:async]
         Thread.current[THREAD_KEY] = ctx
 
-        Thread.current[TIMING_THREAD_KEY] = [id, Process.clock_gettime(Process::CLOCK_MONOTONIC)] if @threshold
+        if @threshold
+          Thread.current[TIMING_ID_KEY]    = id
+          Thread.current[TIMING_START_KEY] = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
 
         # Enrich the current span directly. When OTel instruments via driver-level
         # prepend (Trilogy, PG, Mysql2), the span is created BEFORE this notification
@@ -96,15 +124,12 @@ module RailsOtelContext
       end
 
       def finish(_name, id, _payload)
-        if @threshold
-          entry = Thread.current[TIMING_THREAD_KEY]
-          if entry&.first.equal?(id)
-            Thread.current[TIMING_THREAD_KEY] = nil
-            elapsed_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - entry[1]) * 1000
-            if elapsed_ms >= @threshold
-              span = OpenTelemetry::Trace.current_span
-              span.set_attribute(DB_SLOW_ATTR, true) if span.context.valid?
-            end
+        if @threshold && Thread.current[TIMING_ID_KEY].equal?(id)
+          elapsed_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - Thread.current[TIMING_START_KEY]) * 1000
+          Thread.current[TIMING_ID_KEY] = nil
+          if elapsed_ms >= @threshold
+            span = OpenTelemetry::Trace.current_span
+            span.set_attribute(DB_SLOW_ATTR, true) if span.context.valid?
           end
         end
       ensure
@@ -168,9 +193,10 @@ module RailsOtelContext
     end
 
     def clear!
-      Thread.current[THREAD_KEY] = nil
+      Thread.current[THREAD_KEY]       = nil
       Thread.current[SCOPE_THREAD_KEY] = nil
-      Thread.current[TIMING_THREAD_KEY] = nil
+      Thread.current[TIMING_ID_KEY]    = nil
+      Thread.current[TIMING_START_KEY] = nil
     end
 
     # Test helpers: set AR context directly for unit tests.
@@ -193,6 +219,7 @@ module RailsOtelContext
       span.set_attribute('code.activerecord.method', ctx[:method_name]) if ctx[:method_name]
       span.set_attribute('code.activerecord.scope', ctx[:scope_name]) if ctx[:scope_name]
       span.set_attribute('db.query_count', ctx[:query_count]) if ctx[:query_count]
+      span.set_attribute('db.async', true) if ctx[:async]
 
       formatter = RailsOtelContext.configuration.span_name_formatter
       return unless formatter
@@ -216,18 +243,109 @@ module RailsOtelContext
     end
 
     # Parses "Transaction Load" → { model_name: "Transaction", method_name: "Load" }
+    # Uses index+byteslice instead of split to avoid allocating the intermediate Array
+    # and two String copies — saves 1 alloc (Array) vs split which returns Array+Strings
+    # but with frozen_string_literal the slice shares storage on MRI 3.2+.
     def parse_ar_name(name)
       return nil unless name
 
-      parts = name.split(' ', 2)
-      return nil unless parts.size == 2
+      idx = name.index(' ')
+      return nil unless idx
 
-      model_name = parts[0]
-      method_name = parts[1]
+      model_name  = name[0, idx]
+      method_name = name[idx + 1, name.length]
 
       return nil if model_name == 'ActiveRecord'
 
-      { model_name: model_name, method_name: method_name }
+      { model_name: model_name, method_name: method_name,
+        query_key: "#{model_name}.#{method_name}".freeze }
+    end
+
+    # Parses raw SQL (payload[:name] == "SQL") to extract model context.
+    # Used for counter cache updates, touch_later, and connection.execute calls
+    # that fire sql.active_record with name="SQL" rather than "Model Method".
+    #
+    # Returns nil when the table cannot be mapped to a known AR model, so callers
+    # fall through to the existing skip path.
+    def parse_sql_context(sql)
+      return nil unless sql
+
+      verb = sql[SQL_VERB_RE, 1]&.capitalize
+      return nil unless verb
+
+      keyword = case verb
+                when 'Update'          then KW_UPDATE
+                when 'Insert'          then KW_INTO
+                when 'Delete', 'Select' then KW_FROM
+                end
+      return nil unless keyword
+
+      table = extract_table_after(sql, keyword)
+      return nil unless table
+
+      model_name = ar_table_model_map[table]
+      return nil unless model_name
+
+      { model_name: model_name, method_name: verb,
+        query_key: "#{model_name}.#{verb}".freeze }
+    end
+
+    # Extracts a table name from +sql+ starting after +keyword+.
+    # Skips one optional leading quote character (` " '), reads word chars until
+    # the next delimiter (space, quote, comma). Returns nil when keyword not found.
+    # Saves 1 alloc vs regex: index()+slice allocates only the result String.
+    def extract_table_after(sql, keyword)
+      idx = sql.index(keyword)
+      return nil unless idx
+
+      start = idx + keyword.length
+      first = sql.getbyte(start)
+      start += 1 if first == BYTE_BACKTICK || first == BYTE_DQUOTE || first == BYTE_SQUOTE # rubocop:disable Style/MultipleComparison
+
+      stop = start
+      stop += 1 while stop < sql.length &&
+                      (b = sql.getbyte(stop)) != BYTE_SPACE &&
+                      b != BYTE_BACKTICK && b != BYTE_DQUOTE && b != BYTE_SQUOTE && b != BYTE_COMMA
+
+      stop > start ? sql[start, stop - start] : nil
+    end
+
+    # Lazy table_name → model_name index. Built on first use after all models are
+    # loaded (eager_load! in production). In development, call reset_ar_table_model_map!
+    # after a code reload to get a fresh index.
+    def ar_table_model_map
+      @ar_table_model_map ||= begin
+        next_map = {}
+        if defined?(::ActiveRecord::Base)
+          ::ActiveRecord::Base.descendants.each do |m|
+            model_name = begin
+              m.name
+            rescue StandardError
+              next
+            end
+            next unless model_name
+            # Skip STI subclasses — they share the parent's table_name.
+            # Without this guard, AdminUser < User would overwrite users → User
+            # with users → AdminUser in the map, giving wrong model names on
+            # SQL-named spans (counter caches, update_all).
+            next unless m.base_class == m
+
+            table = begin
+              m.table_name
+            rescue StandardError
+              next
+            end
+            next unless table
+
+            next_map[table] = model_name
+          end
+        end
+        next_map
+      end
+    end
+
+    def reset_ar_table_model_map!
+      @ar_table_model_map = nil
     end
   end
 end

data/lib/rails_otel_context/adapters/mysql2.rb

@@ -36,10 +36,7 @@ module RailsOtelContext
           %i[query prepare].each do |method_name|
             define_method(method_name) do |*args|
               result = super(*args)
-
-              span = OpenTelemetry::Trace.current_span
-              mod.apply_source_to_span(span, mod.source_location_for_app) if span.context.valid?
-
+              mod.apply_call_site_to_span(OpenTelemetry::Trace.current_span, mod.call_site_for_app)
               result
             end
           end

data/lib/rails_otel_context/adapters/pg.rb

@@ -45,10 +45,12 @@ module RailsOtelContext
           # AR context and span renaming handled by CallContextProcessor.apply_db_context.
           methods.each do |method_name|
             define_method(method_name) do |*args, &user_block|
-              source = mod.source_location_for_app
+              # 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_source_to_span(OpenTelemetry::Trace.current_span, source)
+                mod.apply_call_site_to_span(OpenTelemetry::Trace.current_span, site)
                 user_block ? user_block.call(result) : result
               end
             end

data/lib/rails_otel_context/adapters/trilogy.rb

@@ -35,10 +35,7 @@ module RailsOtelContext
           # AR context and span renaming handled by CallContextProcessor.apply_db_context.
           define_method(:query) do |sql|
             result = super(sql)
-
-            span = OpenTelemetry::Trace.current_span
-            mod.apply_source_to_span(span, mod.source_location_for_app) if span.context.valid?
-
+            mod.apply_call_site_to_span(OpenTelemetry::Trace.current_span, mod.call_site_for_app)
             result
           end
         end

data/lib/rails_otel_context/call_context_processor.rb

@@ -4,28 +4,39 @@ module RailsOtelContext
   # SpanProcessor that enriches all spans with the calling Ruby class and method name,
   # and optionally with user-defined custom attributes.
   #
-  # Sets two attributes on every span (unless the call stack yields no app-code frame):
+  # Sets span attributes (unless the call stack yields no app-code frame):
   #   - code.namespace  – the class name, e.g. "OrderService", "InvoiceJob"
   #   - code.function   – the method name, e.g. "create", "perform"
+  #   - code.filepath   – app-relative source file
+  #   - code.lineno     – source line number
   #
-  # Class names are extracted from the frame label when available (e.g. "User.find"),
-  # and inferred from the file-path basename otherwise (e.g. order_service.rb → OrderService).
-  #
-  # Frames inside gems or outside app_root are always skipped.
+  # Three-tier call-context resolution (fastest to slowest):
+  #   1. Pushed frame  — O(1) thread-local read. Set by Railtie around_action for
+  #                      controllers, or manually via RailsOtelContext.with_frame.
+  #   2. Stack walk    — O(stack depth). Falls back here when no frame is pushed.
+  #                      DB adapters (Trilogy, PG, MySQL2) additionally overwrite
+  #                      code.* attributes post-query from a shallower stack position,
+  #                      giving the exact call site (e.g. UserRepository#find_active:23).
   #
   # Custom attributes (configured via +custom_span_attributes+) are applied to every span.
   # The callable must return a Hash (or nil) and must be fast — it runs in the hot path
   # of every span creation. Exceptions in the callable are silently rescued to avoid
   # disrupting application request processing.
   class CallContextProcessor
+    include RailsOtelContext::SourceLocation
+
     SPAN_CONTROLLER_ATTR = 'request.controller'
     SPAN_ACTION_ATTR     = 'request.action'
     AR_MODEL_ATTR        = 'code.activerecord.model'
     AR_METHOD_ATTR       = 'code.activerecord.method'
     AR_SCOPE_ATTR        = 'code.activerecord.scope'
     AR_QUERY_COUNT_ATTR  = 'db.query_count'
+    AR_ASYNC_ATTR        = 'db.async'
     ORIG_NAME_ATTR       = 'l9.orig.name'
 
+    # Exposed so SourceLocation mixin can use it for the stack-walk path.
+    attr_reader :app_root
+
     def initialize(app_root:, config: RailsOtelContext.configuration)
       @app_root = app_root.to_s
       @request_context_enabled = config.request_context_enabled
@@ -49,17 +60,28 @@ module RailsOtelContext
     private
 
     def apply_call_context(span)
+      # Fast path: caller pushed a frame explicitly — O(1), zero allocations.
+      # DB adapters will overwrite this with the exact call site post-query.
+      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
+
+      # Fallback: walk the call stack. DB spans without a pushed frame take this
+      # path; the adapter's post-query walk (shallower) will overwrite the result.
       return unless Thread.respond_to?(:each_caller_location)
 
-      context = extract_caller_context
-      return unless context
+      site = call_site_for_app
+      return unless site
 
-      span.set_attribute('code.namespace', context[:class_name])
-      span.set_attribute('code.function', context[:method_name]) if context[:method_name]
-      return unless context[:lineno]
+      span.set_attribute('code.namespace', site[:class_name])
+      span.set_attribute('code.function', site[:method_name]) if site[:method_name]
+      return unless site[:lineno]
 
-      span.set_attribute('code.filepath', context[:filepath])
-      span.set_attribute('code.lineno', context[:lineno])
+      span.set_attribute('code.filepath', site[:filepath])
+      span.set_attribute('code.lineno', site[:lineno])
     end
 
     def apply_request_context(span)
@@ -95,6 +117,7 @@ module RailsOtelContext
       span.set_attribute(AR_METHOD_ATTR, ar_context[:method_name]) if ar_context[:method_name]
       span.set_attribute(AR_SCOPE_ATTR, ar_context[:scope_name]) if ar_context[:scope_name]
       span.set_attribute(AR_QUERY_COUNT_ATTR, ar_context[:query_count]) if ar_context[:query_count]
+      span.set_attribute(AR_ASYNC_ATTR, true) if ar_context[:async]
     end
 
     def apply_span_name_formatter(span, ar_context)
@@ -118,33 +141,5 @@ module RailsOtelContext
     rescue StandardError
       # Never let a user-supplied callback break span processing.
     end
-
-    def extract_caller_context
-      Thread.each_caller_location do |location|
-        path = location.absolute_path || location.path
-        next unless path&.start_with?(@app_root)
-        next if path.include?('/gems/')
-
-        label    = location.label || ''
-        lineno   = location.lineno
-        filepath = path.delete_prefix("#{@app_root}/")
-
-        # Try label first: "ClassName.method" or "ClassName#method"
-        if label =~ /^([A-Z][a-zA-Z0-9_]*(?:::[A-Z][a-zA-Z0-9_]*)*)(\.|\#)/
-          class_name  = Regexp.last_match(1)
-          method_name = label.split(/[.\#]/, 2).last
-                             &.sub(/^(?:block|rescue|ensure) in /, '')
-          return { class_name: class_name, method_name: method_name, lineno: lineno, filepath: filepath }
-        end
-
-        # Fallback: infer class from file-path basename (snake_case → CamelCase)
-        class_name  = File.basename(path, '.rb').split('_').map(&:capitalize).join
-        method_name = label.sub(/^(?:block|rescue|ensure) in /, '')
-        return { class_name: class_name, method_name: method_name.empty? ? nil : method_name,
-                 lineno: lineno, filepath: filepath }
-      end
-
-      nil
-    end
   end
 end

data/lib/rails_otel_context/frame_context.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RailsOtelContext
+  # Thread-local storage for explicitly pushed call-frame context.
+  #
+  # The default code.namespace / code.function attributes are extracted by
+  # walking the Ruby call stack on every span start. That works, but costs
+  # O(stack depth) object allocations per span. FrameContext eliminates the
+  # walk by letting call sites push their class+method once at entry:
+  #
+  #   RailsOtelContext::FrameContext.with_frame(class_name: 'OrdersController',
+  #                                             method_name: 'create') do
+  #     # every span created inside here reads the pushed frame — no stack walk
+  #   end
+  #
+  # The Railtie automatically installs an around_action that pushes the
+  # controller frame for all controller actions. For jobs, service objects, or
+  # any other code that creates spans, use +with_frame+ directly or include
+  # +RailsOtelContext::Frameable+.
+  #
+  # The pushed frame is a fallback for the span processor: the stack walk
+  # still runs when no frame is pushed, so existing behavior is preserved.
+  module FrameContext
+    FRAME_KEY = :_rails_otel_ctx_frame
+    private_constant :FRAME_KEY
+
+    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:)
+        prev = Thread.current[FRAME_KEY]
+        Thread.current[FRAME_KEY] = { class_name: class_name, method_name: method_name }.freeze
+        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
+      end
+
+      # Clears the pushed frame. Pair with +push+ in an ensure block.
+      def pop
+        Thread.current[FRAME_KEY] = nil
+      end
+
+      # Returns the currently pushed frame hash, or nil.
+      def current
+        Thread.current[FRAME_KEY]
+      end
+
+      alias clear! pop
+    end
+  end
+
+  # Include in any class to get a +with_otel_frame+ convenience wrapper that
+  # pushes self.class.name + the calling method name automatically.
+  #
+  #   class InvoiceService
+  #     include RailsOtelContext::Frameable
+  #
+  #     def call
+  #       with_otel_frame { do_work }
+  #     end
+  #   end
+  module Frameable
+    def with_otel_frame(method_name = nil, &)
+      name = method_name || caller_locations(1, 1).first&.label || '<unknown>'
+      FrameContext.with_frame(class_name: self.class.name, method_name: name, &)
+    end
+  end
+end

data/lib/rails_otel_context/railtie.rb

@@ -20,6 +20,20 @@ module RailsOtelContext
       end
     end
 
+    # Push the controller class + action name as the active frame for every
+    # controller action. Replaces the O(stack-depth) walk with a O(1) thread-local
+    # read for every span created during the action. Always-on — no config gate.
+    initializer 'rails_otel_context.install_frame_context' do
+      ActiveSupport.on_load(:action_controller) do
+        around_action do |_controller, block|
+          RailsOtelContext::FrameContext.with_frame(
+            class_name: self.class.name,
+            method_name: action_name
+          ) { block.call }
+        end
+      end
+    end
+
     # Install request context capture on ActionController when it loads.
     # Uses around_action with ensure for leak-proof cleanup on exceptions.
     initializer 'rails_otel_context.install_request_context' do

data/lib/rails_otel_context/source_location.rb

@@ -1,28 +1,100 @@
 # frozen_string_literal: true
 
 module RailsOtelContext
-  # Shared helper for finding the first app-code source location in the call stack.
-  # Used by all DB adapters to attach source file/line to query spans.
+  # Shared call-site extraction for DB adapters and CallContextProcessor.
+  #
+  # Every adapter (Trilogy, PG, MySQL2) includes this on class << self and
+  # calls call_site_for_app after (or around) the query. Because the adapter
+  # is closer to user code in the call stack than CallContextProcessor#on_start
+  # is, the walk reaches the app frame in fewer iterations — and returns
+  # class + method + filepath + lineno in one shot.
+  #
+  # CallContextProcessor includes this too so it can share the same logic in
+  # its stack-walk fallback path.
   module SourceLocation
+    # Regex constants — compiled once, shared by all includers.
+    CLASS_LABEL_RE  = /^([A-Z][a-zA-Z0-9_]*(?:::[A-Z][a-zA-Z0-9_]*)*)[.#]/
+    BLOCK_LABEL_RE  = /^(?:block|rescue|ensure) in /
+    METHOD_SPLIT_RE = /[.#]/
+    private_constant :CLASS_LABEL_RE, :BLOCK_LABEL_RE, :METHOD_SPLIT_RE
+
+    # Returns the first app-code frame as a Hash:
+    #   { class_name:, method_name:, filepath:, lineno: }
+    # Returns nil when no app frame is found or the feature is unavailable.
+    # Requires +app_root+ to be defined on the including object.
+    def call_site_for_app
+      return unless Thread.respond_to?(:each_caller_location)
+
+      Thread.each_caller_location do |location|
+        path = location.absolute_path || location.path
+        next unless path&.start_with?(app_root)
+        next if path.include?('/gems/')
+
+        return build_call_site(location, path)
+      end
+
+      nil
+    end
+
+    # Applies all four call-site attributes to +span+ in one go.
+    def apply_call_site_to_span(span, site)
+      return unless site && span.context.valid?
+
+      span.set_attribute('code.namespace', site[:class_name])
+      span.set_attribute('code.function',  site[:method_name]) if site[:method_name]
+      span.set_attribute('code.filepath',  site[:filepath])
+      span.set_attribute('code.lineno',    site[:lineno]) if site[:lineno]
+    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
       return unless Thread.respond_to?(:each_caller_location)
 
+      prefix = app_root_prefix
       Thread.each_caller_location do |location|
         path = location.absolute_path || location.path
         next unless path&.start_with?(app_root)
         next if path.include?('/gems/')
 
-        return [path.delete_prefix("#{app_root}/"), location.lineno]
+        return [path.delete_prefix(prefix), location.lineno]
       end
 
       nil
     end
 
+    # Legacy helper — use apply_call_site_to_span for new code.
     def apply_source_to_span(span, source)
       return unless source
 
       span.set_attribute('code.filepath', source[0])
-      span.set_attribute('code.lineno', source[1])
+      span.set_attribute('code.lineno',   source[1])
+    end
+
+    private
+
+    def app_root_prefix
+      @app_root_prefix ||= "#{app_root}/"
+    end
+
+    def build_call_site(location, path)
+      label    = location.label || ''
+      lineno   = location.lineno
+      filepath = path.delete_prefix(app_root_prefix)
+
+      if label =~ CLASS_LABEL_RE
+        class_name  = Regexp.last_match(1)
+        method_name = label.split(METHOD_SPLIT_RE, 2).last
+                           &.sub(BLOCK_LABEL_RE, '')
+        return { class_name: class_name, method_name: method_name,
+                 lineno: lineno, filepath: filepath }
+      end
+
+      class_name  = File.basename(path, '.rb').split('_').map(&:capitalize).join
+      method_name = label.sub(BLOCK_LABEL_RE, '')
+      { class_name: class_name,
+        method_name: method_name.empty? ? nil : method_name,
+        lineno: lineno, filepath: filepath }
     end
   end
 end

data/lib/rails_otel_context/version.rb

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

data/lib/rails_otel_context.rb

@@ -12,6 +12,7 @@ require 'rails_otel_context/source_location'
 require 'rails_otel_context/activerecord_context'
 require 'rails_otel_context/adapters'
 require 'rails_otel_context/request_context'
+require 'rails_otel_context/frame_context'
 require 'rails_otel_context/call_context_processor'
 require 'rails_otel_context/railtie' if defined?(Rails::Railtie)
 
@@ -28,5 +29,18 @@ module RailsOtelContext
     def reset_configuration!
       @configuration = Configuration.new
     end
+
+    # 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)
+    end
+
+    def push_frame(class_name:, method_name:)
+      FrameContext.push(class_name: class_name, method_name: method_name)
+    end
+
+    def pop_frame
+      FrameContext.pop
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-otel-context
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Last9
@@ -71,6 +71,7 @@ files:
 - lib/rails_otel_context/adapters/trilogy.rb
 - lib/rails_otel_context/call_context_processor.rb
 - lib/rails_otel_context/configuration.rb
+- lib/rails_otel_context/frame_context.rb
 - lib/rails_otel_context/railtie.rb
 - lib/rails_otel_context/request_context.rb
 - lib/rails_otel_context/source_location.rb