request_trail 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef1bf3bfcc191f502a9380fbe03bcdba11db1003b6b061db77b93769ac8697ba
-  data.tar.gz: 6df870ef886ee153cda6babf4cb75c2d80484c9d42c61fccd926fe5278a42705
+  metadata.gz: 170ab890527afbaf7d18005ceca802f6a561795724cce97e1f9740f100dcc1ea
+  data.tar.gz: 91e793b4cf8bf1b086ac2908177bd618e8aabd71a37f239e45b115c9f986290e
 SHA512:
-  metadata.gz: 484a485f9ffd159c6daf55abd72f9dc44204d483b2ed31242e502433224c7adf59b33a211e1fd501d703437caa1c4158775b463f0c3c4cdd7156283078ed3b89
-  data.tar.gz: 99d772953da1f97dea448fb3e50bf8889c7a1e29fae0a67805e210d949cddbacad5e039bd7d59821480109c6a62566e73d3575d21a0f61badf3c19e5eec08731
+  metadata.gz: 59cceaa66b3ff236a3a9bab1637f78db87455c5beb1e8687bc89f459053803fd12b52131862923b1d26561cb6c349dee2c970e0cdd421216445758cd1ea6fc21
+  data.tar.gz: e8969dd6df420ff10c3e3a2879ace0a187797633e98764ddf152b28e1d435a4a0099825afb8af64859d8dd1eff6d9403251e9b88c4f249251efe12995f1dc0af

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [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 +19,6 @@
 - `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.2.0...HEAD
+[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

@@ -39,9 +39,14 @@ gem install request_trail
 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] GET /orders 142ms | SQL: 7 queries / 38ms
+[RequestTrail] GET /orders 142ms | SQL: 7/38.3ms | Cache: 4 hits, 1 miss, 2.0ms
 ```
 
+The summary line shows:
+- **Total request time** in milliseconds
+- **SQL** — query count and cumulative Active Record time
+- **Cache** — hit/miss/write counts and cumulative cache time
+
 ### Configuration
 
 Add an initializer to customize behavior:

data/ROADMAP.md

@@ -2,14 +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`

data/lib/request_trail/collector.rb

@@ -4,7 +4,8 @@ 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
 
     def self.current
       Thread.current[THREAD_KEY]
@@ -22,6 +23,10 @@ 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
     end
 
     def record_sql(duration_ms)
@@ -29,6 +34,16 @@ 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 elapsed_ms
       elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at
       (elapsed * 1000).round(2)

data/lib/request_trail/formatter.rb

@@ -4,14 +4,20 @@ 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} #{collector.elapsed_ms.round}ms | #{sql_summary(collector)} | #{cache_summary(collector)}"
     end
 
     private
 
     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
   end
 end

data/lib/request_trail/subscriber.rb

@@ -2,20 +2,43 @@
 
 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"
 
     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]
     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
   end
 end

data/lib/request_trail/version.rb

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

data/sig/request_trail/collector.rbs

@@ -0,0 +1,30 @@
+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
+
+    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
+
+    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 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,5 @@
+module RequestTrail
+  class Formatter
+    def format: (::Rack::Request request, 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,18 @@
+module RequestTrail
+  class Subscriber
+    SQL_EVENT: String
+    CACHE_READ_EVENT: String
+    CACHE_WRITE_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
+  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.2.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