request_trail 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c636ff49dd9c5f372269c4e9a9611a7e610e5e5f6f172a951e1f7d76579f804
-  data.tar.gz: 2e7a528107b38f1c3e92d0bc11bbdfd2b51295daaf616f4e6cbb82dbe8cc71e1
+  metadata.gz: 46f0f0b5ac13bf9ea151c441b9de780076a0350c34a4268258701bd4bc9e2bd6
+  data.tar.gz: 0d1823f675d5074c2b1ee8664970737b81ac9a3b3535a58a1f56bdf029f5089e
 SHA512:
-  metadata.gz: c4d2694d6a22c9a24884968967cb4210771e12efd1d43934df844dbdf699382ec994e620b0d6f75773b6584c5ae2f4a4c6cd6f346f808c400e70c36603b59352
-  data.tar.gz: f8597a5b458895afa2d09081ba96fd422c971733918f64a2a7109133103e12b0725fdb20d4ec2efc2b7d8a8dca383d241037796b69c10d902b5bd819085a6700
+  metadata.gz: 2d1bf8caea4104913b8a4ef9c1b1c4aa517d4aaeb96f83f5fa49242ceee598cbdb6c118191e6bd0eecacd4ee3bdbaf77293f6725750768dff5dd4a182bfae6ee
+  data.tar.gz: c412309dd55a91d2eeec4c9cbed03999a1dc4e317638873ccb7662a384e146ee3af8d3a0f783fa9288047eca475d8cfc578048c54d556354e8fcf66d51a70575

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.7.0] - 2026-06-14
+
+### Added
+
+- `config.n_plus_one_threshold` — flag requests where SQL query count meets or exceeds a threshold; appends `[N+1?]` to the header line in plain-text and FlameGraph output, and sets `"n_plus_one": true` in JSON output (default: `nil` = disabled)
+- `RequestTrail::ActiveJobSubscriber` — module to include in `ApplicationJob`; adds an `around_perform` hook that traces background job execution across all ActiveJob backends (GoodJob, Solid Queue, DelayedJob, Sidekiq-via-ActiveJob)
+- Outbound HTTP tracking — `Subscriber` subscribes to `request.faraday` notifications; `http_count` and `http_duration_ms` are added to `Collector` and surfaced in all formatters (plain text, FlameGraph, JSON)
+
 ## [0.6.0] - 2026-06-14
 
 ### Added
@@ -58,7 +66,9 @@
 - `RequestTrail::Subscriber` — attach/detach API for notification subscriptions
 - `RequestTrail::Collector` — thread-safe per-request event accumulator
 
-[Unreleased]: https://github.com/eclectic-coding/request-trail/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/eclectic-coding/request-trail/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/eclectic-coding/request-trail/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/eclectic-coding/request-trail/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/eclectic-coding/request-trail/releases/tag/v0.5.0
 [0.4.0]: https://github.com/eclectic-coding/request-trail/releases/tag/v0.4.0
 [0.3.0]: https://github.com/eclectic-coding/request-trail/releases/tag/v0.3.0

data/README.md

@@ -12,7 +12,18 @@ Middleware that traces a request through all the layers (middleware, controller,
 
 - [Installation](#installation)
 - [Usage](#usage)
-- [Custom formatters](#custom-formatters)
+  - [Rails](#rails)
+  - [JSON formatter](#json-formatter)
+  - [Flame graph formatter](#flame-graph-formatter)
+  - [N+1 detection](#n1-detection)
+  - [Rails log tags](#rails-log-tags)
+  - [Sidekiq](#sidekiq)
+  - [ActiveJob](#activejob)
+  - [Outbound HTTP tracking](#outbound-http-tracking)
+  - [Custom formatters](#custom-formatters)
+  - [Installation generator](#installation-generator)
+  - [Configuration](#configuration)
+  - [Non-Rails (plain Rack)](#non-rails-plain-rack)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -110,6 +121,115 @@ RequestTrail::Formatters::FlameGraph.new(
 
 Unspecified layers keep their defaults.
 
+### N+1 detection
+
+Set `config.n_plus_one_threshold` to flag requests that fire too many SQL queries. When `sql_count >= threshold`, all formatters add a prominent marker:
+
+```ruby
+RequestTrail.configure do |config|
+  config.n_plus_one_threshold = 10  # nil = disabled (default)
+end
+```
+
+Plain text and FlameGraph append `[N+1?]` to the header line:
+
+```
+[RequestTrail] GET /orders 142ms [N+1?] | SQL: 15/85.0ms | Cache: 0 hits, 0 misses, 0.0ms
+```
+
+JSON includes `"n_plus_one": true` in the payload:
+
+```json
+{"method":"GET","path":"/orders","duration_ms":142.5,"n_plus_one":true,"sql":{"count":15,"duration_ms":85.0},...}
+```
+
+### Rails log tags
+
+Add `RequestTrail.log_tag` to `config.log_tags` to include live request state on every tagged log line. The callable returns a lazy value that evaluates to `sql=N Nms` at log-line format time — so it reflects the accumulated query state at each point during the request:
+
+```ruby
+# config/application.rb
+config.log_tags = [:request_id, RequestTrail.log_tag]
+```
+
+Example output:
+
+```
+[abc-123] [sql=3 25ms] Completed 200 OK in 25ms
+[abc-123] [sql=3 25ms] [RequestTrail] GET /orders 25ms | SQL: 3/10.0ms | Cache: 0 hits, 0 misses, 0.0ms
+```
+
+The tag is omitted (blank-suppressed by Rails) on lines that fall outside an active request.
+
+### Sidekiq
+
+Add `RequestTrail::SidekiqMiddleware` to the Sidekiq server middleware chain to trace background job execution with the same flame-graph output:
+
+```ruby
+# config/initializers/sidekiq.rb
+Sidekiq.configure_server do |config|
+  config.server_middleware do |chain|
+    chain.add RequestTrail::SidekiqMiddleware
+  end
+end
+```
+
+Output uses `JOB` as the method and includes the worker class and job ID:
+
+```
+[RequestTrail] JOB HardWorker jid:abc123 42ms | SQL: 5/35.0ms | Cache: 0 hits, 0 misses, 0.0ms
+```
+
+All configuration options (`threshold_ms`, `sample_rate`, `n_plus_one_threshold`, `formatter`, etc.) apply to Sidekiq jobs the same way they apply to HTTP requests.
+
+### ActiveJob
+
+Include `RequestTrail::ActiveJobSubscriber` in `ApplicationJob` to trace background jobs across all ActiveJob backends (GoodJob, Solid Queue, DelayedJob, Sidekiq-via-ActiveJob, etc.):
+
+```ruby
+# app/jobs/application_job.rb
+class ApplicationJob < ActiveJob::Base
+  include RequestTrail::ActiveJobSubscriber
+end
+```
+
+All jobs that inherit from `ApplicationJob` are then automatically traced. Output uses `JOB` as the method and includes the job class and `job_id`:
+
+```
+[RequestTrail] JOB OrderSyncJob jid:476b61a6-ae85-4ae8-ae64-bf92e8cfeefc 42ms | SQL: 5/35.0ms | Cache: 0 hits, 0 misses, 0.0ms
+```
+
+All configuration options (`threshold_ms`, `sample_rate`, `n_plus_one_threshold`, `formatter`, etc.) apply to ActiveJob jobs the same way they apply to HTTP requests.
+
+**`ActiveJobSubscriber` vs `SidekiqMiddleware`:** Use `ActiveJobSubscriber` when you want adapter-agnostic tracing via `ApplicationJob` inheritance. Use `SidekiqMiddleware` when running Sidekiq workers that do *not* go through ActiveJob (i.e., plain `Sidekiq::Worker` classes).
+
+### Outbound HTTP tracking
+
+Outbound HTTP calls made via Faraday are tracked automatically once `Subscriber.attach` is called (which happens via the Railtie in Rails apps). No additional configuration is needed — the `request.faraday` notification is subscribed alongside SQL and cache events.
+
+Plain text output includes an `HTTP` segment:
+
+```
+[RequestTrail] GET /orders 142ms | SQL: 7/38.3ms | Cache: 4 hits, 1 miss, 2.0ms | HTTP: 2/45.0ms
+```
+
+Tiered output adds an `http` row under the controller:
+
+```
+[RequestTrail] GET /orders 142ms
+  controller  104ms
+    sql        38ms (7 queries)
+    cache       2ms (4 hits, 1 miss)
+    view       22ms
+    http       45ms (2 calls)
+```
+
+JSON output includes an `"http"` key:
+
+```json
+{"method":"GET","path":"/orders","duration_ms":142.5,...,"http":{"count":2,"duration_ms":45.0}}
+```
+
 ### Custom formatters
 
 Any object that responds to `format(request, collector)` and returns a `String` can be used as a formatter. Include `RequestTrail::Formatters::Base` to make the contract explicit:
@@ -130,7 +250,7 @@ end
 
 `format` receives:
 - `request` — a `Rack::Request` with the current HTTP request
-- `collector` — a `RequestTrail::Collector` exposing `elapsed_ms`, `sql_count`, `sql_duration_ms`, `cache_hits`, `cache_misses`, `cache_duration_ms`, `action_duration_ms`, and `view_duration_ms`
+- `collector` — a `RequestTrail::Collector` exposing `elapsed_ms`, `sql_count`, `sql_duration_ms`, `cache_hits`, `cache_misses`, `cache_duration_ms`, `action_duration_ms`, `view_duration_ms`, `http_count`, and `http_duration_ms`
 
 ### Installation generator
 
@@ -149,17 +269,20 @@ Add an initializer to customize behavior:
 ```ruby
 # config/initializers/request_trail.rb
 RequestTrail.configure do |config|
-  config.enabled       = true      # set to false to disable entirely
-  config.log_level     = :info     # Rails logger level (:debug, :info, :warn)
-  config.threshold_ms  = 200       # only log requests slower than this (0 = log all)
-  config.logger        = nil       # defaults to Rails.logger
-  config.formatter     = RequestTrail::Formatters::FlameGraph.new  # optional
+  config.enabled              = true      # set to false to disable entirely
+  config.log_level            = :info     # Rails logger level (:debug, :info, :warn)
+  config.threshold_ms         = 200       # only log requests slower than this (0 = log all)
+  config.logger               = nil       # defaults to Rails.logger
+  config.formatter            = RequestTrail::Formatters::FlameGraph.new  # optional
 
   # skip tracing for specific paths (strings = exact match, regexes = pattern match)
-  config.ignore_paths  = ["/health", "/up", /^\/assets/]
+  config.ignore_paths         = ["/health", "/up", /^\/assets/]
 
   # trace only N% of requests — useful in high-traffic production environments
-  config.sample_rate   = 0.1      # 0.0 = never, 1.0 = always (default)
+  config.sample_rate          = 0.1      # 0.0 = never, 1.0 = always (default)
+
+  # flag requests with too many SQL queries (nil = disabled)
+  config.n_plus_one_threshold = 10
 end
 ```
 

data/lib/generators/request_trail/install/templates/request_trail.rb.tt

@@ -6,6 +6,7 @@ RequestTrail.configure do |config|
   config.threshold_ms = 0       # only log requests slower than this (0 = log all)
   config.ignore_paths = []      # e.g. ["/health", /^\/assets/]
   config.sample_rate  = 1.0     # 0.0–1.0; 1.0 = trace every request
+  # config.n_plus_one_threshold = nil  # warn when sql_count >= N (nil = disabled)
 
   # config.logger    = Rails.logger  # defaults to Rails.logger
   # config.formatter = RequestTrail::Formatters::FlameGraph.new(colorize: true)

data/lib/request_trail/active_job_subscriber.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RequestTrail
+  module ActiveJobSubscriber
+    JobContext = Struct.new(:request_method, :path, keyword_init: true)
+
+    def self.included(base)
+      base.around_perform { |job, block| RequestTrail::ActiveJobSubscriber.trace(job, block) }
+    end
+
+    def self.trace(job, block)
+      if RequestTrail.configuration.enabled && RequestTrail.configuration.sampled?
+        Collector.start
+        block.call
+        log(job)
+      else
+        block.call
+      end
+    ensure
+      Collector.stop
+    end
+
+    def self.log(job)
+      collector = Collector.current
+      return if collector.elapsed_ms < RequestTrail.configuration.threshold_ms
+
+      message = RequestTrail.formatter.format(build_context(job), collector)
+      RequestTrail.configuration.logger.send(RequestTrail.configuration.log_level, message)
+    end
+
+    def self.build_context(job)
+      JobContext.new(
+        request_method: "JOB",
+        path: "#{job.class.name || job.class.to_s} jid:#{job.job_id}"
+      )
+    end
+  end
+end

data/lib/request_trail/collector.rb

@@ -6,7 +6,8 @@ module RequestTrail
 
     attr_reader :sql_count, :sql_duration_ms,
                 :cache_hits, :cache_misses, :cache_writes, :cache_duration_ms,
-                :action_duration_ms, :view_duration_ms
+                :action_duration_ms, :view_duration_ms,
+                :http_count, :http_duration_ms
 
     def self.current
       Thread.current[THREAD_KEY]
@@ -30,6 +31,8 @@ module RequestTrail
       @cache_duration_ms = 0.0
       @action_duration_ms = 0.0
       @view_duration_ms = 0.0
+      @http_count = 0
+      @http_duration_ms = 0.0
     end
 
     def record_sql(duration_ms)
@@ -52,6 +55,11 @@ module RequestTrail
       @view_duration_ms = view_duration_ms
     end
 
+    def record_http(duration_ms:)
+      @http_count += 1
+      @http_duration_ms += duration_ms
+    end
+
     def elapsed_ms
       elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at
       (elapsed * 1000).round(2)

data/lib/request_trail/configuration.rb

@@ -5,7 +5,7 @@ require "logger"
 module RequestTrail
   class Configuration
     attr_writer :logger, :formatter
-    attr_accessor :enabled, :log_level, :threshold_ms, :ignore_paths, :sample_rate
+    attr_accessor :enabled, :log_level, :threshold_ms, :ignore_paths, :sample_rate, :n_plus_one_threshold
 
     def initialize
       @enabled = true
@@ -13,6 +13,7 @@ module RequestTrail
       @threshold_ms = 0
       @ignore_paths = []
       @sample_rate = 1.0
+      @n_plus_one_threshold = nil
     end
 
     def sampled?

data/lib/request_trail/formatter.rb

@@ -5,10 +5,11 @@ module RequestTrail
     include Formatters::Base
 
     def format(request, collector)
-      header = "[RequestTrail] #{request.request_method} #{request.path} #{collector.elapsed_ms.round}ms"
+      n1 = n_plus_one?(collector) ? " [N+1?]" : ""
+      header = "[RequestTrail] #{request.request_method} #{request.path} #{collector.elapsed_ms.round}ms#{n1}"
       return tiered_format(header, collector) if collector.action_duration_ms.positive?
 
-      "#{header} | #{sql_summary(collector)} | #{cache_summary(collector)}"
+      "#{header} | #{sql_summary(collector)} | #{cache_summary(collector)} | #{http_summary(collector)}"
     end
 
     private
@@ -19,7 +20,8 @@ module RequestTrail
         "  controller  #{collector.action_duration_ms.round}ms",
         "    sql        #{collector.sql_duration_ms.round(1)}ms (#{sql_count_label(collector)})",
         "    cache      #{collector.cache_duration_ms.round(1)}ms (#{cache_detail(collector)})",
-        "    view       #{collector.view_duration_ms.round(1)}ms"
+        "    view       #{collector.view_duration_ms.round(1)}ms",
+        "    http       #{collector.http_duration_ms.round(1)}ms (#{http_count_label(collector)})"
       ].join("\n")
     end
 
@@ -34,6 +36,14 @@ module RequestTrail
       "Cache: #{collector.cache_hits} #{hit_label}, #{collector.cache_misses} #{miss_label}, #{duration}ms"
     end
 
+    def http_summary(collector)
+      "HTTP: #{collector.http_count}/#{collector.http_duration_ms.round(1)}ms"
+    end
+
+    def http_count_label(collector)
+      collector.http_count == 1 ? "1 call" : "#{collector.http_count} calls"
+    end
+
     def sql_count_label(collector)
       collector.sql_count == 1 ? "1 query" : "#{collector.sql_count} queries"
     end

data/lib/request_trail/formatters/base.rb

@@ -12,6 +12,13 @@ module RequestTrail
       def format(_request, _collector)
         raise NotImplementedError, "#{self.class}#format must return a String"
       end
+
+      private
+
+      def n_plus_one?(collector)
+        threshold = RequestTrail.configuration.n_plus_one_threshold
+        threshold ? collector.sql_count >= threshold : false
+      end
     end
   end
 end

data/lib/request_trail/formatters/flame_graph.rb

@@ -13,7 +13,8 @@ module RequestTrail
         controller: "\e[34m",
         sql: "\e[33m",
         cache: "\e[32m",
-        view: "\e[35m"
+        view: "\e[35m",
+        http: "\e[36m"
       }.freeze
       RESET = "\e[0m"
 
@@ -41,21 +42,24 @@ module RequestTrail
           row("  ", "controller", collector.action_duration_ms, total, :controller),
           row("    ", "sql",      collector.sql_duration_ms,    total, :sql),
           row("    ", "cache",    collector.cache_duration_ms,  total, :cache),
-          row("    ", "view",     collector.view_duration_ms,   total, :view)
+          row("    ", "view",     collector.view_duration_ms,   total, :view),
+          row("    ", "http",     collector.http_duration_ms,   total, :http)
         ]
       end
 
       def flat_rows(collector, total)
         [
           row("  ", "sql",   collector.sql_duration_ms,   total, :sql),
-          row("  ", "cache", collector.cache_duration_ms, total, :cache)
+          row("  ", "cache", collector.cache_duration_ms, total, :cache),
+          row("  ", "http",  collector.http_duration_ms,  total, :http)
         ]
       end
 
       def header_line(request, collector)
         elapsed = collector.elapsed_ms.round
         bar = BAR_CHAR * BAR_WIDTH
-        line = "[RequestTrail] #{request.request_method} #{request.path} #{elapsed}ms #{bar}"
+        n1 = n_plus_one?(collector) ? " [N+1?]" : ""
+        line = "[RequestTrail] #{request.request_method} #{request.path} #{elapsed}ms#{n1} #{bar}"
         return line unless colorize?
 
         "#{@colors[:header]}#{line}#{RESET}"

data/lib/request_trail/formatters/json.rb

@@ -20,8 +20,10 @@ module RequestTrail
           method: request.request_method,
           path: request.path,
           duration_ms: collector.elapsed_ms,
+          n_plus_one: n_plus_one?(collector),
           sql: { count: collector.sql_count, duration_ms: collector.sql_duration_ms },
-          cache: cache_payload(collector)
+          cache: cache_payload(collector),
+          http: { count: collector.http_count, duration_ms: collector.http_duration_ms }
         }
       end
 

data/lib/request_trail/subscriber.rb

@@ -6,9 +6,11 @@ module RequestTrail
     CACHE_READ_EVENT  = "cache_read.active_support"
     CACHE_WRITE_EVENT = "cache_write.active_support"
     ACTION_EVENT      = "process_action.action_controller"
+    HTTP_EVENT        = "request.faraday"
 
     def self.attach
-      @attach ||= [sql_subscription, cache_read_subscription, cache_write_subscription, action_subscription]
+      @attach ||= [sql_subscription, cache_read_subscription, cache_write_subscription,
+                   action_subscription, http_subscription]
     end
 
     def self.detach
@@ -51,5 +53,12 @@ module RequestTrail
         )
       end
     end
+
+    private_class_method def self.http_subscription
+      ActiveSupport::Notifications.subscribe(HTTP_EVENT) do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        Collector.current&.record_http(duration_ms: event.duration)
+      end
+    end
   end
 end

data/lib/request_trail/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RequestTrail
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/request_trail.rb

@@ -10,6 +10,7 @@ require_relative "request_trail/formatters/flame_graph"
 require_relative "request_trail/formatters/json"
 require_relative "request_trail/log_tag"
 require_relative "request_trail/middleware"
+require_relative "request_trail/active_job_subscriber" if defined?(ActiveJob)
 require_relative "request_trail/sidekiq_middleware" if defined?(Sidekiq)
 require_relative "request_trail/railtie" if defined?(Rails::Railtie)
 

data/sig/request_trail/active_job_subscriber.rbs

@@ -0,0 +1,15 @@
+module RequestTrail
+  module ActiveJobSubscriber
+    class JobContext
+      attr_accessor request_method: String
+      attr_accessor path: String
+
+      def initialize: (request_method: String, path: String) -> void
+    end
+
+    def self.included: (Module base) -> void
+    def self.trace: (untyped job, ^() -> void block) -> void
+    def self.log: (untyped job) -> void
+    def self.build_context: (untyped job) -> JobContext
+  end
+end

data/sig/request_trail/collector.rbs

@@ -20,6 +20,8 @@ module RequestTrail
     attr_reader cache_duration_ms: Float
     attr_reader action_duration_ms: Float
     attr_reader view_duration_ms: Float
+    attr_reader http_count: Integer
+    attr_reader http_duration_ms: Float
 
     def self.current: () -> Collector?
     def self.start: () -> Collector
@@ -30,6 +32,7 @@ module RequestTrail
     def record_cache_read: (hit: bool, duration_ms: Float) -> Float
     def record_cache_write: (duration_ms: Float) -> Float
     def record_action: (duration_ms: Float, view_duration_ms: Float) -> Float
+    def record_http: (duration_ms: Float) -> Float
     def elapsed_ms: () -> (Float | Integer)
   end
 end

data/sig/request_trail/configuration.rbs

@@ -7,6 +7,7 @@ module RequestTrail
     attr_accessor threshold_ms: Numeric
     attr_accessor ignore_paths: Array[String | Regexp]
     attr_accessor sample_rate: Float
+    attr_accessor n_plus_one_threshold: Integer?
 
     def initialize: () -> void
     def logger: () -> ::Logger

data/sig/request_trail/formatters/base.rbs

@@ -2,6 +2,10 @@ module RequestTrail
   module Formatters
     module Base
       def format: (_RequestContext request, Collector collector) -> String
+
+      private
+
+      def n_plus_one?: (Collector collector) -> bool
     end
   end
-end
+end

data/sig/request_trail/subscriber.rbs

@@ -4,6 +4,7 @@ module RequestTrail
     CACHE_READ_EVENT: String
     CACHE_WRITE_EVENT: String
     ACTION_EVENT: String
+    HTTP_EVENT: String
 
     self.@attach: Array[untyped]?
 
@@ -16,5 +17,6 @@ module RequestTrail
     def self.cache_read_subscription: () -> untyped
     def self.cache_write_subscription: () -> untyped
     def self.action_subscription: () -> untyped
+    def self.http_subscription: () -> untyped
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: request_trail
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -57,6 +57,7 @@ files:
 - lib/generators/request_trail/install/install_generator.rb
 - lib/generators/request_trail/install/templates/request_trail.rb.tt
 - lib/request_trail.rb
+- lib/request_trail/active_job_subscriber.rb
 - lib/request_trail/collector.rb
 - lib/request_trail/configuration.rb
 - lib/request_trail/formatter.rb
@@ -70,6 +71,7 @@ files:
 - lib/request_trail/subscriber.rb
 - lib/request_trail/version.rb
 - sig/request_trail.rbs
+- sig/request_trail/active_job_subscriber.rbs
 - sig/request_trail/collector.rbs
 - sig/request_trail/configuration.rbs
 - sig/request_trail/formatter.rbs