rails-otel-context 0.8.5 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c77108c1ddfab7776d31052f6633e7ec132aafb415f682099f571e5c4758db89
-  data.tar.gz: 262506de5a8bc5a4bbfa74341bdb79113fd54f4d0fe6d247c51cb35db395b006
+  metadata.gz: 592224b44e9a4b7b72a85624dbfea6b05717b629ff9e707a4975cfc6db276b18
+  data.tar.gz: '0757947daefb592c0ef3e63c4d2396fb049461224c244aa145d51218c9f12f28'
 SHA512:
-  metadata.gz: 6dd47b5fcaea795a44e9e2db032fd77ccfddb97bef173be6ff1c19499e52e5ffbe26ff3b8a9ce8a5d4bf145f2f2aa58cd115aac04ac7ebf166d6dc98d0401ae6
-  data.tar.gz: 5ac0a1d07185865a92f79bab9895b04f5405b7f4a4978f6ded96878ad1b4bb0ed76c093bcd1a7ab912f5c1935f6989fb692fc4dd9d9000a2f211b294c777123d
+  metadata.gz: 1a695932a41348bf86b042b9535b95c9423161ac33873af45539386d3602225de51d430d9d01ac979736742a6cc79377a335d1f2dc07f93281cbdbaf71cfb89d
+  data.tar.gz: defbc699fa36e0ad33b907965ee6bb4cc47b7190d82acebede64f395bc25534bc6710b59de621f3693e7d33e82be705aa96ad1db95c101dfefdf3efd779089c1

data/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/last9/rails-otel-context/actions/workflows/ci.yml/badge.svg)](https://github.com/last9/rails-otel-context/actions/workflows/ci.yml)
 [![Gem Version](https://img.shields.io/gem/v/rails-otel-context)](https://rubygems.org/gems/rails-otel-context)
 
-OpenTelemetry spans for Rails know a lot about your database. They know the SQL. They know how long it took. What they don't know is *which code fired that query* — the model, the scope, the controller, the line number. This gem fixes that.
+OpenTelemetry spans for Rails know a lot about your database. They know the SQL. They know how long it took. What they don't know is *which code fired that query* — the service object, the scope, the job, the line number. This gem fixes that.
 
 ## Before and after
 
@@ -26,111 +26,162 @@ With this gem:
   "db.system": "postgresql",
   "db.statement": "SELECT * FROM transactions WHERE ...",
   "duration_ms": 450,
-  "code.activerecord.model": "Transaction",
+  "code.activerecord.model":  "Transaction",
   "code.activerecord.method": "Load",
-  "code.activerecord.scope": "recent_completed",
-  "code.namespace": "DashboardController",
-  "code.function": "index",
-  "code.filepath": "app/controllers/dashboard_controller.rb",
-  "code.lineno": 14,
-  "db.query_count": 47
+  "code.activerecord.scope":  "recent_completed",
+  "code.namespace":           "BillingService",
+  "code.function":            "monthly_summary",
+  "code.filepath":            "app/services/billing_service.rb",
+  "code.lineno":              42,
+  "rails.controller":         "ReportsController",
+  "rails.action":             "index",
+  "db.query_count":           3
 }
 ```
 
-You navigate straight to the offending line. No grepping, no guessing.
+Notice `code.namespace` is `BillingService`, not `ReportsController` — the gem walks the call stack and finds the service object that actually issued the query, not the controller that dispatched the request. No configuration required.
 
 ## Installation
 
 ```ruby
-gem 'rails-otel-context', '~> 0.7'
+gem 'rails-otel-context', '~> 0.9'
 ```
 
-That's it. Everything installs automatically when Rails boots.
+Add the gem, boot Rails. Everything else happens automatically.
+
+## What gets added to your spans
+
+Every span — DB, Redis, HTTP outbound, custom — gets:
+
+| Attribute | Example | Where it comes from |
+|---|---|---|
+| `code.namespace` | `"BillingService"` | Nearest app-code class in the call stack |
+| `code.function` | `"monthly_summary"` | Method within that class |
+| `code.filepath` | `"app/services/billing_service.rb"` | App-relative path |
+| `code.lineno` | `42` | Source line number |
+| `rails.controller` | `"ReportsController"` | Current Rails controller (set for every request) |
+| `rails.action` | `"index"` | Current Rails action |
+| `rails.job` | `"MonthlyInvoiceJob"` | ActiveJob class (set for every job, mutually exclusive with `rails.controller`) |
+
+DB spans additionally get:
+
+| Attribute | Example | Description |
+|---|---|---|
+| `code.activerecord.model` | `"Transaction"` | ActiveRecord model |
+| `code.activerecord.method` | `"Load"` | AR operation (Load, Count, Update…) |
+| `code.activerecord.scope` | `"recent_completed"` | Named scope or class method |
+| `db.query_count` | `3` | Occurrence count this request — 2nd+ flags N+1 patterns |
+| `db.slow` | `true` | Set when duration ≥ `slow_query_threshold_ms` |
+| `db.async` | `true` | Set when issued via `load_async` (Rails 7.1+) |
 
 ## Configuration
 
-The defaults are sensible. A production initializer that gets the most out of this gem:
+Zero configuration gets you everything above. The optional initializer adds span naming and slow-query detection:
 
 ```ruby
 # config/initializers/rails_otel_context.rb
 RailsOtelContext.configure do |c|
-  # Rename DB spans to Model.scope — makes traces scannable at a glance
-  c.span_name_formatter = ->(original, ar) {
+  # Rename DB spans: prefer scope name, then calling method, then AR operation
+  #
+  # Priority (highest to lowest):
+  #   1. scope_name   — named scope or class method returning a Relation
+  #                     e.g. User.active, Transaction.recent_completed
+  #   2. code_function when code_namespace == model — the model's own class method
+  #                     e.g. Transaction.total_revenue, User.for_account
+  #   3. method_name  — AR operation: Load, Count, Update, Destroy…
+  #                     e.g. Transaction.Load, Transaction.Update
+  c.span_name_formatter = lambda { |original, ar|
     model = ar[:model_name]
     return original unless model
 
-    scope = ar[:scope_name] ||
-            (ar[:code_function] if ar[:code_namespace] == model && !ar[:code_function]&.start_with?('<')) ||
-            ar[:method_name]
-    "#{model}.#{scope}"
-  }
+    scope   = ar[:scope_name]
+    code_fn = ar[:code_function]
+    code_ns = ar[:code_namespace]
+    ar_op   = ar[:method_name]
 
-  # Carry controller + action name into every DB span fired during the request
-  c.request_context_enabled = true
+    method = if scope
+               scope
+             elsif code_fn && code_ns == model && !code_fn.start_with?('<')
+               code_fn
+             else
+               ar_op
+             end
 
-  # Flag slow queries (sets db.slow: true on spans exceeding the threshold)
+    "#{model}.#{method}"
+  }
+
+  # Flag slow queries
   c.slow_query_threshold_ms = 500
 
-  # Attach any per-request context to every span in the trace
-  c.custom_span_attributes = -> { { 'team' => Current.team } if Current.team }
+  # Attach any per-request context to every span
+  c.custom_span_attributes = -> { { 'tenant' => Current.tenant } if Current.tenant }
 end
 ```
 
-## What gets added to your spans
+## How `code.namespace` / `code.function` works
 
-| Attribute | Example | Description |
+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.
+
+This means the right class shows up automatically at every layer:
+
+| Caller | `code.namespace` | `code.function` |
 |---|---|---|
-| `code.activerecord.model` | `"Transaction"` | ActiveRecord model name |
-| `code.activerecord.method` | `"Load"` | AR operation (Load, Count, Update…) |
-| `code.activerecord.scope` | `"recent_completed"` | Named scope or class method that produced the query |
-| `code.namespace` | `"DashboardController"` | Ruby class that triggered the span |
-| `code.function` | `"index"` | Method name within that class |
-| `code.filepath` | `"app/controllers/..."` | App-relative source file |
-| `code.lineno` | `14` | Line number |
-| `request.controller` | `"DashboardController"` | Rails controller (requires `request_context_enabled`) |
-| `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+) |
+| `ReportsController#index` calls `BillingService#monthly_summary` which queries | `BillingService` | `monthly_summary` |
+| `UserRepository#find_active` queries directly | `UserRepository` | `find_active` |
+| `OrdersController#create` queries directly | `OrdersController` | `create` |
+| `MonthlyInvoiceJob#perform` queries | `MonthlyInvoiceJob` | `perform` |
+
+No `include` statements. No `with_frame` calls. The nearest frame wins.
+
+### Override for hot paths
+
+The stack walk is O(stack depth) — roughly 15–25 frame iterations before reaching app code. For code paths that create thousands of spans per second, `FrameContext.with_frame` replaces the walk with a single thread-local read:
+
+```ruby
+class ReportingPipeline
+  include RailsOtelContext::Frameable
+
+  def run
+    # All spans inside this block skip the stack walk.
+    # code.namespace: "ReportingPipeline", code.function: "run"
+    with_otel_frame { process_all_accounts }
+  end
+end
+```
+
+The pushed frame takes priority for the duration of the block. Outside the block, automatic stack-walk resumes.
 
 ## Span naming
 
-Without a formatter, DB spans arrive named by the driver (`SELECT`, `INSERT`). The formatter in the example above renames them using what this gem knows about each query:
+Without a formatter, DB spans carry the driver's name (`SELECT`, `INSERT`). With the example formatter above:
 
-| What fired the query | Available context | Span name |
-|---|---|---|
-| `Transaction.recent_completed.to_a` | `scope_name: "recent_completed"` | `Transaction.recent_completed` |
-| `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` |
+| Query | Result |
+|---|---|
+| `Transaction.recent_completed.to_a` | `Transaction.recent_completed` |
+| `Transaction.total_revenue` (class method) | `Transaction.total_revenue` |
+| `Transaction.where(...).first` | `Transaction.Load` |
+| `record.update(...)` | `Transaction.Update` |
+| Counter cache / `connection.execute` | `User.Update` (SQL parsed → table → model) |
 
-The original span name is preserved in `l9.orig.name` so you can always filter on the raw driver operation.
+The original name is preserved in `l9.orig.name`.
 
 ### 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:
+Rails counter caches, `touch_later`, and `connection.execute` fire `sql.active_record` with `payload[:name] = "SQL"`. The gem parses the statement and maps the table back to an 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!
+UPDATE `users` SET `users`.`comments_count` = ...
+  → code.activerecord.model: "User", method: "Update"
+  → span renamed to "User.Update"
 ```
 
 ### Scope tracking
 
-The gem captures scope names from both the `scope` macro and plain class methods that return a relation:
+Both `scope` macro methods and plain class methods returning a Relation are captured:
 
 ```ruby
 class Transaction < ApplicationRecord
-  scope :recent_completed, -> { where(...) }  # captured as code.activerecord.scope
+  scope :recent_completed, -> { where(...) }  # code.activerecord.scope: "recent_completed"
 
   def self.for_account(id)                     # also captured
     where(account_id: id)
@@ -138,59 +189,34 @@ class Transaction < ApplicationRecord
 end
 ```
 
-## Redis
-
-Redis source location tracking is off by default — it fires on every cache read and most Redis calls are fast. Turn it on when debugging:
-
-```ruby
-c.redis_source_enabled = true
-```
-
-## ClickHouse
-
-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:
+## Redis and ClickHouse
 
-```
-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)
+Redis and ClickHouse spans get the same `code.*` attributes pointing to the app-code frame that issued the call:
 
-All allocation budgets met.
+```json
+{
+  "name": "SET",
+  "db.system": "redis",
+  "code.namespace": "SessionStore",
+  "code.function": "write",
+  "code.filepath": "app/lib/session_store.rb",
+  "code.lineno": 18,
+  "rails.controller": "SessionsController",
+  "rails.action": "create"
+}
 ```
 
-Exits 1 if any path exceeds its budget. Update the budget constant in `bench/allocation_guard.rb` whenever a deliberate trade-off is made.
+## Performance
 
-### Full profiling suite
+`CallContextProcessor#on_start` fires for every span. For a typical 10–20 span request the overhead is in the low-microsecond range and does not require configuration.
 
-Throughput, per-call allocations with top allocating lines, and a StackProf CPU flamegraph:
+For code paths that generate hundreds of spans per second, `FrameContext.with_frame` / `Frameable#with_otel_frame` replace the per-span stack walk with a single thread-local read. See [Override for hot paths](#override-for-hot-paths).
 
-```
-bundle exec ruby bench/subscriber_hot_path.rb
-```
+### Boot cost
 
-The flamegraph dump lands at `tmp/subscriber.dump`. View it with:
+`ScopeNameTracking` hooks `singleton_method_added` on every AR model to detect class methods returning a Relation. On a large app (100+ models), this fires thousands of times during warm-up — one `source_location` call and one method redefinition per class method in `app/`. This is a one-time startup cost, not a per-request cost.
 
-```
-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 |
+`ar_table_model_map` is built once at boot from `AR::Base.descendants`. In development, call `RailsOtelContext::ActiveRecordContext.reset_ar_table_model_map!` after a code reload if model names look stale.
 
 ## Requirements
 

data/lib/rails_otel_context/call_context_processor.rb

@@ -1,32 +1,32 @@
 # frozen_string_literal: true
 
 module RailsOtelContext
-  # SpanProcessor that enriches all spans with the calling Ruby class and method name,
-  # and optionally with user-defined custom attributes.
+  # SpanProcessor that enriches ALL spans with:
+  #   - code.namespace / code.function / code.filepath / code.lineno
+  #     (nearest app-code frame from the call stack — automatic, no manual setup)
+  #   - rails.controller / rails.action   (when inside a controller action)
+  #   - rails.job                         (when inside a job)
   #
-  # 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
+  # Call-context resolution:
+  #   1. Explicit override — O(1). If app code calls FrameContext.with_frame (or
+  #      includes Frameable), that frame wins. Use this to intentionally override
+  #      the automatic nearest-frame (e.g., to expose a service boundary rather
+  #      than the inner repo it delegates to).
+  #   2. Stack walk — O(stack depth). Default path when no override is active.
+  #      DB adapters (Trilogy, PG, MySQL2, Redis, ClickHouse) additionally overwrite
+  #      code.* post-query from a shallower position, giving exact call-site precision.
   #
-  # 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).
+  # rails.* attributes come from RequestContext (thread-local set by Railtie hooks)
+  # and are applied unconditionally — no config gate.
   #
-  # 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.
+  # Custom attributes (configured via +custom_span_attributes+) are also applied.
+  # The callable must return a Hash (or nil) and must be fast — hot path per span.
   class CallContextProcessor
     include RailsOtelContext::SourceLocation
 
-    SPAN_CONTROLLER_ATTR = 'request.controller'
-    SPAN_ACTION_ATTR     = 'request.action'
+    SPAN_CONTROLLER_ATTR = 'rails.controller'
+    SPAN_ACTION_ATTR     = 'rails.action'
+    SPAN_JOB_ATTR        = 'rails.job'
     AR_MODEL_ATTR        = 'code.activerecord.model'
     AR_METHOD_ATTR       = 'code.activerecord.method'
     AR_SCOPE_ATTR        = 'code.activerecord.scope'
@@ -38,16 +38,15 @@ module RailsOtelContext
     attr_reader :app_root
 
     def initialize(app_root:, config: RailsOtelContext.configuration)
-      @app_root = app_root.to_s
-      @request_context_enabled     = config.request_context_enabled
-      @custom_span_attributes      = config.custom_span_attributes
-      @span_name_formatter         = config.span_name_formatter
-      @slow_query_threshold_ms     = config.slow_query_threshold_ms
+      @app_root                = app_root.to_s
+      @custom_span_attributes  = config.custom_span_attributes
+      @span_name_formatter     = config.span_name_formatter
+      @slow_query_threshold_ms = config.slow_query_threshold_ms
     end
 
     def on_start(span, _parent_context)
       apply_call_context(span)
-      apply_request_context(span) if @request_context_enabled
+      apply_request_context(span)
       apply_db_context(span)
       apply_custom_attributes(span) if @custom_span_attributes
     end
@@ -79,34 +78,39 @@ module RailsOtelContext
     private
 
     def apply_call_context(span)
-      # Fast path: caller pushed a frame explicitly — O(1), zero allocations.
+      # 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]
+        span.set_attribute('code.function',  pushed[:method_name]) if pushed[:method_name]
         return
       end
 
-      # Fallback: walk the call stack to find the first app-code frame.
+      # 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
       return unless site
 
       span.set_attribute('code.namespace', site[:class_name])
-      span.set_attribute('code.function', site[:method_name]) if site[:method_name]
+      span.set_attribute('code.function',  site[:method_name]) if site[:method_name]
       return unless site[:lineno]
 
       span.set_attribute('code.filepath', site[:filepath])
-      span.set_attribute('code.lineno', site[:lineno])
+      span.set_attribute('code.lineno',   site[:lineno])
     end
 
     def apply_request_context(span)
       controller, action = RequestContext.fetch
-      return unless controller
+      if controller
+        span.set_attribute(SPAN_CONTROLLER_ATTR, controller)
+        span.set_attribute(SPAN_ACTION_ATTR, action) if action
+        return
+      end
 
-      span.set_attribute(SPAN_CONTROLLER_ATTR, controller)
-      span.set_attribute(SPAN_ACTION_ATTR, action) if action
+      job = RequestContext.job
+      span.set_attribute(SPAN_JOB_ATTR, job) if job
     end
 
     def apply_db_context(span)

data/lib/rails_otel_context/configuration.rb

@@ -5,9 +5,12 @@ module RailsOtelContext
     attr_accessor :redis_source_enabled,
                   :clickhouse_enabled,
                   :span_name_formatter,
-                  :request_context_enabled,
                   :slow_query_threshold_ms
 
+    # Deprecated: rails.controller / rails.action / rails.job are now always set
+    # on every span. This option is kept for backwards compatibility and has no effect.
+    attr_accessor :request_context_enabled
+
     attr_reader :custom_span_attributes
 
     def initialize

data/lib/rails_otel_context/railtie.rb

@@ -35,41 +35,33 @@ module RailsOtelContext
       RailsOtelContext::ActiveRecordContext.reset_ar_table_model_map!
     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
+    # 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.
+    initializer 'rails_otel_context.install_request_context' do
       ActiveSupport.on_load(:action_controller) do
         around_action do |_controller, block|
-          # Reset N+1 query counter at the start of every request so counts
-          # never bleed across requests on Puma's reused threads. This runs
-          # regardless of request_context_enabled, which only gates whether
-          # RequestContext.set is called (and would reset it there too).
-          Thread.current[RailsOtelContext::RequestContext::QUERY_COUNT_KEY] = nil
-          RailsOtelContext::FrameContext.with_frame(
-            class_name: self.class.name,
-            method_name: action_name
-          ) { block.call }
+          RailsOtelContext::RequestContext.set(
+            controller: self.class.name,
+            action: action_name
+          )
+          block.call
         ensure
-          Thread.current[RailsOtelContext::RequestContext::QUERY_COUNT_KEY] = nil
+          RailsOtelContext::RequestContext.clear!
         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
-      ActiveSupport.on_load(:action_controller) do
-        if RailsOtelContext.configuration.request_context_enabled
-          around_action do |_controller, block|
-            RailsOtelContext::RequestContext.set(
-              controller: self.class.name,
-              action: action_name
-            )
-            block.call
-          ensure
-            RailsOtelContext::RequestContext.clear!
-          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

data/lib/rails_otel_context/request_context.rb

@@ -1,19 +1,24 @@
 # frozen_string_literal: true
 
 module RailsOtelContext
-  # Thread-local storage for request-scoped context that gets propagated
-  # to all spans within a request. Uses raw Thread.current for minimal overhead —
-  # no object allocation, no mutex, ~5ns per read/write.
+  # Thread-local storage for request/job-scoped context propagated to all spans.
+  # Uses raw Thread.current — no object allocation, no mutex, ~5ns per read/write.
   #
-  # Lifecycle:
+  # Controller lifecycle:
   #   1. Railtie's around_action sets controller + action at request start
   #   2. CallContextProcessor reads them on every child span's on_start
   #   3. around_action's ensure block clears them when the request ends
   #
-  # Thread safety: each Puma thread has its own slot — no sharing, no contention.
+  # Job lifecycle:
+  #   1. Railtie's around_perform sets job at job start
+  #   2. CallContextProcessor reads it on every child span's on_start
+  #   3. around_perform's ensure block clears it when the job ends
+  #
+  # Thread safety: each Puma/Sidekiq thread owns its slot — no sharing, no contention.
   module RequestContext
     CONTROLLER_KEY  = :_rails_otel_ctx_controller
     ACTION_KEY      = :_rails_otel_ctx_action
+    JOB_KEY         = :_rails_otel_ctx_job
     QUERY_COUNT_KEY = :_rails_otel_ctx_qcount
 
     class << self
@@ -23,6 +28,11 @@ module RailsOtelContext
         Thread.current[QUERY_COUNT_KEY] = nil
       end
 
+      def set_job(job_class:)
+        Thread.current[JOB_KEY]         = job_class
+        Thread.current[QUERY_COUNT_KEY] = nil
+      end
+
       # Returns [controller, action] in a single Thread.current access.
       def fetch
         t = Thread.current
@@ -37,9 +47,19 @@ module RailsOtelContext
         Thread.current[ACTION_KEY]
       end
 
+      def job
+        Thread.current[JOB_KEY]
+      end
+
       def clear!
         Thread.current[CONTROLLER_KEY]  = nil
         Thread.current[ACTION_KEY]      = nil
+        Thread.current[JOB_KEY]         = nil
+        Thread.current[QUERY_COUNT_KEY] = nil
+      end
+
+      def clear_job!
+        Thread.current[JOB_KEY]         = nil
         Thread.current[QUERY_COUNT_KEY] = nil
       end
     end

data/lib/rails_otel_context/version.rb

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

metadata

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