request_trail 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef1bf3bfcc191f502a9380fbe03bcdba11db1003b6b061db77b93769ac8697ba
-  data.tar.gz: 6df870ef886ee153cda6babf4cb75c2d80484c9d42c61fccd926fe5278a42705
+  metadata.gz: 954b1805423f92d59582e41e86d55ac489577ef5c76d20701c0fbcd76956f2a8
+  data.tar.gz: 8464e352949c6eb14636ead83e5f0a556b8eb7dcabfd35186f35b3749ae8ac0a
 SHA512:
-  metadata.gz: 484a485f9ffd159c6daf55abd72f9dc44204d483b2ed31242e502433224c7adf59b33a211e1fd501d703437caa1c4158775b463f0c3c4cdd7156283078ed3b89
-  data.tar.gz: 99d772953da1f97dea448fb3e50bf8889c7a1e29fae0a67805e210d949cddbacad5e039bd7d59821480109c6a62566e73d3575d21a0f61badf3c19e5eec08731
+  metadata.gz: 2c75f6813431fe8922454592a7dfb170fbddab4258a696901e79d0e1ec56699834cd7d9d0200d8eef1a7a3067dc95988e7bd0419b66b0ee6566bf0f342301dfd
+  data.tar.gz: 7054bee0d5f25f35513c9697bfe5000128d7932df335beae13acaeb43af5522fde160c045554526a505efacbe326d9892689756b4ea8b289d04869d7c73fc565

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-12
+
+### Added
+
+- Controller and view tracing via `process_action.action_controller` — records total controller duration and view runtime per request
+- Formatter switches to tiered multi-line output when controller data is present:
+  ```
+  [RequestTrail] GET /orders 142ms
+    controller  104ms
+      sql        38ms (7 queries)
+      cache       2ms (4 hits, 1 miss)
+      view       22ms
+  ```
+
+## [0.2.0] - 2026-06-11
+
+### Added
+
+- Cache tracing via `cache_read.active_support` and `cache_write.active_support` notifications — records hit/miss/write counts and cumulative duration per request
+- Summary line now includes a cache segment: `[RequestTrail] GET /orders 142ms | SQL: 7/38.3ms | Cache: 4 hits, 1 miss, 2.0ms`
+
 ## [0.1.0] - 2026-06-11
 
 ### Added
@@ -12,5 +33,7 @@
 - `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.1.0...HEAD
+[Unreleased]: https://github.com/eclectic-coding/request-trail/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/eclectic-coding/request-trail/releases/tag/v0.3.0
+[0.2.0]: https://github.com/eclectic-coding/request-trail/releases/tag/v0.2.0
 [0.1.0]: https://github.com/eclectic-coding/request-trail/releases/tag/v0.1.0

data/README.md

@@ -36,10 +36,22 @@ gem install request_trail
 
 ### Rails
 
-RequestTrail auto-inserts itself via a Railtie. No manual middleware configuration is needed — just add the gem to your `Gemfile` and it will log a summary after every request:
+RequestTrail auto-inserts itself via a Railtie. No manual middleware configuration is needed — just add the gem to your `Gemfile` and it will log a summary after every request.
+
+When controller tracing is active, output is tiered:
+
+```
+[RequestTrail] GET /orders 142ms
+  controller  104ms
+    sql        38ms (7 queries)
+    cache       2ms (4 hits, 1 miss)
+    view       22ms
+```
+
+Without controller data (plain Rack apps), a single-line summary is emitted:
 
 ```
-[RequestTrail] GET /orders 142ms | SQL: 7 queries / 38ms
+[RequestTrail] GET /orders 142ms | SQL: 7/38.3ms | Cache: 4 hits, 1 miss, 2.0ms
 ```
 
 ### Configuration
@@ -73,9 +85,42 @@ run MyApp
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run the full CI suite (audit + lint + tests). You can also run `bin/console` for an interactive prompt.
+
+### Running tests
+
+```bash
+bundle exec rake spec          # full test suite
+bundle exec rspec spec/path/to/file_spec.rb  # single file
+bundle exec rspec spec/path/to/file_spec.rb:42  # single example
+```
+
+### Dummy app
+
+A minimal Rails app lives in `spec/dummy` for manual end-to-end testing. It mounts a single `GET /ping` endpoint and logs RequestTrail output to `spec/dummy/log/request_trail.log`.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Start the server:
+
+```bash
+bundle exec rackup spec/dummy/config.ru --port 3000
+```
+
+Then make a request and tail the log:
+
+```bash
+curl http://localhost:3000/ping
+tail -f spec/dummy/log/request_trail.log
+```
+
+You should see tiered output like:
+
+```
+[RequestTrail] GET /ping 33ms
+  controller  3ms
+    sql        0.0ms (0 queries)
+    cache      0.0ms (0 hits, 0 misses)
+    view       2.8ms
+```
 
 [Back to top](#requesttrail)
 

data/ROADMAP.md

@@ -2,26 +2,6 @@
 
 `request_trail` traces a Rails request through every processing layer — middleware, controller, ActiveRecord, cache — and emits a flame-graph-style summary to the log. This roadmap describes the incremental path to a stable 1.0.0.
 
-## 0.2.0 — Cache Tracing
-
-- Subscribe to `cache_read`, `cache_write`, `cache_fetch_hit`, and `cache_delete` notifications
-- Add cache hit/miss/write counts and cumulative time to the summary line:
-  ```
-  [RequestTrail] GET /orders 142ms | SQL: 7/38ms | Cache: 4 hits, 1 miss, 2ms
-  ```
-
-## 0.3.0 — Controller & View Tracing
-
-- Subscribe to `process_action.action_controller` and `render_template.action_view`
-- Tiered multi-line breakdown showing time spent in each layer:
-  ```
-  [RequestTrail] GET /orders 142ms
-    controller  104ms
-      sql        38ms (7 queries)
-      cache       2ms (4 hits, 1 miss)
-      view       22ms
-  ```
-
 ## 0.4.0 — Flame Graph Output
 
 - Indented ASCII flame-graph renderer with proportional timing bars
@@ -42,6 +22,7 @@
 - Slow-request mode: only emit summaries above `threshold_ms`
 - Sampling: trace only N% of requests (useful in production)
 - Custom formatter API: `config.formatter = MyFormatter`
+- Rails generator to scaffold the config initializer (`rails generate request_trail:install`)
 
 ## 0.6.0 — Structured Output & Integrations
 

data/lib/request_trail/collector.rb

@@ -4,7 +4,9 @@ module RequestTrail
   class Collector
     THREAD_KEY = :request_trail_collector
 
-    attr_reader :sql_count, :sql_duration_ms
+    attr_reader :sql_count, :sql_duration_ms,
+                :cache_hits, :cache_misses, :cache_writes, :cache_duration_ms,
+                :action_duration_ms, :view_duration_ms
 
     def self.current
       Thread.current[THREAD_KEY]
@@ -22,6 +24,12 @@ module RequestTrail
       @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       @sql_count = 0
       @sql_duration_ms = 0.0
+      @cache_hits = 0
+      @cache_misses = 0
+      @cache_writes = 0
+      @cache_duration_ms = 0.0
+      @action_duration_ms = 0.0
+      @view_duration_ms = 0.0
     end
 
     def record_sql(duration_ms)
@@ -29,6 +37,21 @@ module RequestTrail
       @sql_duration_ms += duration_ms
     end
 
+    def record_cache_read(hit:, duration_ms:)
+      hit ? @cache_hits += 1 : @cache_misses += 1
+      @cache_duration_ms += duration_ms
+    end
+
+    def record_cache_write(duration_ms:)
+      @cache_writes += 1
+      @cache_duration_ms += duration_ms
+    end
+
+    def record_action(duration_ms:, view_duration_ms:)
+      @action_duration_ms = duration_ms
+      @view_duration_ms = view_duration_ms
+    end
+
     def elapsed_ms
       elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at
       (elapsed * 1000).round(2)

data/lib/request_trail/formatter.rb

@@ -3,15 +3,43 @@
 module RequestTrail
   class Formatter
     def format(request, collector)
-      header = "[RequestTrail] #{request.request_method} #{request.path}"
-      "#{header} #{collector.elapsed_ms.round}ms | #{sql_summary(collector)}"
+      header = "[RequestTrail] #{request.request_method} #{request.path} #{collector.elapsed_ms.round}ms"
+      return tiered_format(header, collector) if collector.action_duration_ms.positive?
+
+      "#{header} | #{sql_summary(collector)} | #{cache_summary(collector)}"
     end
 
     private
 
+    def tiered_format(header, collector)
+      [
+        header,
+        "  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"
+      ].join("\n")
+    end
+
     def sql_summary(collector)
-      label = collector.sql_count == 1 ? "query" : "queries"
-      "SQL: #{collector.sql_count} #{label} / #{collector.sql_duration_ms.round(1)}ms"
+      "SQL: #{collector.sql_count}/#{collector.sql_duration_ms.round(1)}ms"
+    end
+
+    def cache_summary(collector)
+      hit_label  = collector.cache_hits == 1 ? "hit" : "hits"
+      miss_label = collector.cache_misses == 1 ? "miss" : "misses"
+      duration   = collector.cache_duration_ms.round(1)
+      "Cache: #{collector.cache_hits} #{hit_label}, #{collector.cache_misses} #{miss_label}, #{duration}ms"
+    end
+
+    def sql_count_label(collector)
+      collector.sql_count == 1 ? "1 query" : "#{collector.sql_count} queries"
+    end
+
+    def cache_detail(collector)
+      hit_label  = collector.cache_hits == 1 ? "hit" : "hits"
+      miss_label = collector.cache_misses == 1 ? "miss" : "misses"
+      "#{collector.cache_hits} #{hit_label}, #{collector.cache_misses} #{miss_label}"
     end
   end
 end

data/lib/request_trail/subscriber.rb

@@ -2,20 +2,54 @@
 
 module RequestTrail
   class Subscriber
-    SQL_EVENT = "sql.active_record"
+    SQL_EVENT         = "sql.active_record"
+    CACHE_READ_EVENT  = "cache_read.active_support"
+    CACHE_WRITE_EVENT = "cache_write.active_support"
+    ACTION_EVENT      = "process_action.action_controller"
 
     def self.attach
-      @attach ||= ActiveSupport::Notifications.subscribe(SQL_EVENT) do |*args|
-        event = ActiveSupport::Notifications::Event.new(*args)
-        Collector.current&.record_sql(event.duration)
-      end
+      @attach ||= [sql_subscription, cache_read_subscription, cache_write_subscription, action_subscription]
     end
 
     def self.detach
       return unless @attach
 
-      ActiveSupport::Notifications.unsubscribe(@attach)
+      @attach&.each { |sub| ActiveSupport::Notifications.unsubscribe(sub) }
       @attach = nil
     end
+
+    private_class_method def self.sql_subscription
+      ActiveSupport::Notifications.subscribe(SQL_EVENT) do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        Collector.current&.record_sql(event.duration)
+      end
+    end
+
+    private_class_method def self.cache_read_subscription
+      ActiveSupport::Notifications.subscribe(CACHE_READ_EVENT) do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        Collector.current&.record_cache_read(
+          hit: event.payload.fetch(:hit, false),
+          duration_ms: event.duration
+        )
+      end
+    end
+
+    private_class_method def self.cache_write_subscription
+      ActiveSupport::Notifications.subscribe(CACHE_WRITE_EVENT) do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        Collector.current&.record_cache_write(duration_ms: event.duration)
+      end
+    end
+
+    private_class_method def self.action_subscription
+      ActiveSupport::Notifications.subscribe(ACTION_EVENT) do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        Collector.current&.record_action(
+          duration_ms: event.duration,
+          view_duration_ms: event.payload.fetch(:view_runtime, 0.0)
+        )
+      end
+    end
   end
 end

data/lib/request_trail/version.rb

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

data/sig/request_trail/collector.rbs

@@ -0,0 +1,35 @@
+module RequestTrail
+  class Collector
+    THREAD_KEY: Symbol
+
+    @started_at: Float
+    @sql_count: Integer
+    @sql_duration_ms: Float
+    @cache_hits: Integer
+    @cache_misses: Integer
+    @cache_writes: Integer
+    @cache_duration_ms: Float
+    @action_duration_ms: Float
+    @view_duration_ms: Float
+
+    attr_reader sql_count: Integer
+    attr_reader sql_duration_ms: Float
+    attr_reader cache_hits: Integer
+    attr_reader cache_misses: Integer
+    attr_reader cache_writes: Integer
+    attr_reader cache_duration_ms: Float
+    attr_reader action_duration_ms: Float
+    attr_reader view_duration_ms: Float
+
+    def self.current: () -> Collector?
+    def self.start: () -> Collector
+    def self.stop: () -> nil
+
+    def initialize: () -> void
+    def record_sql: (Float duration_ms) -> Float
+    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 elapsed_ms: () -> (Float | Integer)
+  end
+end

data/sig/request_trail/configuration.rbs

@@ -0,0 +1,11 @@
+module RequestTrail
+  class Configuration
+    attr_writer logger: ::Logger
+    attr_accessor enabled: bool
+    attr_accessor log_level: Symbol
+    attr_accessor threshold_ms: Numeric
+
+    def initialize: () -> void
+    def logger: () -> ::Logger
+  end
+end

data/sig/request_trail/formatter.rbs

@@ -0,0 +1,13 @@
+module RequestTrail
+  class Formatter
+    def format: (::Rack::Request request, Collector collector) -> String
+
+    private
+
+    def tiered_format: (String header, Collector collector) -> String
+    def sql_summary: (Collector collector) -> String
+    def cache_summary: (Collector collector) -> String
+    def sql_count_label: (Collector collector) -> String
+    def cache_detail: (Collector collector) -> String
+  end
+end

data/sig/request_trail/middleware.rbs

@@ -0,0 +1,6 @@
+module RequestTrail
+  class Middleware
+    def initialize: (untyped app) -> void
+    def call: (Hash[String, untyped] env) -> untyped
+  end
+end

data/sig/request_trail/subscriber.rbs

@@ -0,0 +1,20 @@
+module RequestTrail
+  class Subscriber
+    SQL_EVENT: String
+    CACHE_READ_EVENT: String
+    CACHE_WRITE_EVENT: String
+    ACTION_EVENT: String
+
+    self.@attach: Array[untyped]?
+
+    def self.attach: () -> Array[untyped]
+    def self.detach: () -> nil
+
+    private
+
+    def self.sql_subscription: () -> untyped
+    def self.cache_read_subscription: () -> untyped
+    def self.cache_write_subscription: () -> untyped
+    def self.action_subscription: () -> untyped
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: request_trail
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -63,6 +63,11 @@ files:
 - lib/request_trail/subscriber.rb
 - lib/request_trail/version.rb
 - sig/request_trail.rbs
+- sig/request_trail/collector.rbs
+- sig/request_trail/configuration.rbs
+- sig/request_trail/formatter.rbs
+- sig/request_trail/middleware.rbs
+- sig/request_trail/subscriber.rbs
 homepage: https://github.com/eclectic-coding/request-trail
 licenses:
 - MIT