request_trail 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 170ab890527afbaf7d18005ceca802f6a561795724cce97e1f9740f100dcc1ea
-  data.tar.gz: 91e793b4cf8bf1b086ac2908177bd618e8aabd71a37f239e45b115c9f986290e
+  metadata.gz: ad0751f86ff717630ea62f478707c758fc9d45540721c54016a55e19c86030be
+  data.tar.gz: 6192f331657a761ee7d537c29ded481629cfedfb1da74eb819e9181677010036
 SHA512:
-  metadata.gz: 59cceaa66b3ff236a3a9bab1637f78db87455c5beb1e8687bc89f459053803fd12b52131862923b1d26561cb6c349dee2c970e0cdd421216445758cd1ea6fc21
-  data.tar.gz: e8969dd6df420ff10c3e3a2879ace0a187797633e98764ddf152b28e1d435a4a0099825afb8af64859d8dd1eff6d9403251e9b88c4f249251efe12995f1dc0af
+  metadata.gz: 45d23c714ab2cebe3d5d33db4e8832301e69e496d3cd27419c370eef734bf8581c7d9f815485ab595acf7ce95d9c82c07d580eca805386526edbcd21bfffc74b
+  data.tar.gz: da3154bce7516976fdbff6437b877d639cf9b235a3308cb7101462d63e368b5b64530b932f101975f785cbb18365448e0ef18fbad84c2a5e2d8a3c9db126249c

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-06-12
+
+### Added
+
+- `RequestTrail::Formatters::FlameGraph` — opt-in ASCII flame-graph formatter with proportional `█` bars and per-layer ANSI colour (auto-detected via TTY)
+- Opt in via `config.formatter = RequestTrail::Formatters::FlameGraph.new`
+
+## [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
@@ -19,6 +40,8 @@
 - `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.2.0...HEAD
+[Unreleased]: https://github.com/eclectic-coding/request-trail/compare/v0.4.0...HEAD
+[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
 [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,16 +36,45 @@ 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/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
+### Flame graph formatter
+
+Opt into the ASCII flame-graph formatter for a visual proportional breakdown:
+
+```ruby
+RequestTrail.configure do |config|
+  config.formatter = RequestTrail::Formatters::FlameGraph.new
+end
+```
+
+Output (with ANSI colour when stdout is a TTY):
+
+```
+[RequestTrail] GET /orders 142ms ████████████████████████████████████
+  controller   104ms ████████████████████████████
+    sql         38ms █████████
+    cache        2ms
+    view        22ms █████
+```
+
+Colour scheme: controller = blue, sql = yellow, cache = green, view = magenta. Plain bars are emitted when stdout is not a TTY (e.g. log files, CI).
 
 ### Configuration
 
@@ -58,6 +87,7 @@ RequestTrail.configure do |config|
   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
 end
 ```
 
@@ -78,9 +108,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
 
-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).
+```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`.
+
+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,38 +2,14 @@
 
 `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.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
-- Optional ANSI colour with automatic TTY detection
-- Ships as `Request::Trail::Formatters::FlameGraph` alongside the existing plain-text formatter:
-  ```
-  [RequestTrail] GET /orders 142ms ████████████████████████████████████
-    middleware   4ms  █
-    controller 100ms  ████████████████████████
-      sql       38ms    █████████
-      cache      2ms
-      view      22ms    █████
-  ```
-
 ## 0.5.0 — Filtering & Sampling
 
 - Path filters: skip tracing for `/assets`, `/health`, or custom regex patterns
 - Slow-request mode: only emit summaries above `threshold_ms`
 - Sampling: trace only N% of requests (useful in production)
 - Custom formatter API: `config.formatter = MyFormatter`
+- FlameGraph colour overrides: `FlameGraph.new(colorize: true, colors: { controller: "\e[36m" })`
+- Rails generator to scaffold the config initializer (`rails generate request_trail:install`)
 
 ## 0.6.0 — Structured Output & Integrations
 

data/lib/request_trail/collector.rb

@@ -5,7 +5,8 @@ module RequestTrail
     THREAD_KEY = :request_trail_collector
 
     attr_reader :sql_count, :sql_duration_ms,
-                :cache_hits, :cache_misses, :cache_writes, :cache_duration_ms
+                :cache_hits, :cache_misses, :cache_writes, :cache_duration_ms,
+                :action_duration_ms, :view_duration_ms
 
     def self.current
       Thread.current[THREAD_KEY]
@@ -27,6 +28,8 @@ module RequestTrail
       @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)
@@ -44,6 +47,11 @@ module RequestTrail
       @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/configuration.rb

@@ -4,7 +4,7 @@ require "logger"
 
 module RequestTrail
   class Configuration
-    attr_writer :logger
+    attr_writer :logger, :formatter
     attr_accessor :enabled, :log_level, :threshold_ms
 
     def initialize
@@ -17,6 +17,10 @@ module RequestTrail
       @logger ||= rails_logger || Logger.new($stdout)
     end
 
+    def formatter
+      @formatter ||= RequestTrail::Formatter.new
+    end
+
     private
 
     def rails_logger

data/lib/request_trail/formatter.rb

@@ -3,12 +3,24 @@
 module RequestTrail
   class Formatter
     def format(request, collector)
-      header = "[RequestTrail] #{request.request_method} #{request.path}"
-      "#{header} #{collector.elapsed_ms.round}ms | #{sql_summary(collector)} | #{cache_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)
       "SQL: #{collector.sql_count}/#{collector.sql_duration_ms.round(1)}ms"
     end
@@ -19,5 +31,15 @@ module RequestTrail
       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/formatters/flame_graph.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RequestTrail
+  module Formatters
+    class FlameGraph
+      BAR_WIDTH = 36
+      BAR_CHAR  = "█"
+
+      COLORS = {
+        header: "\e[1m",
+        controller: "\e[34m",
+        sql: "\e[33m",
+        cache: "\e[32m",
+        view: "\e[35m"
+      }.freeze
+      RESET = "\e[0m"
+
+      def initialize(colorize: false)
+        @colorize = colorize
+      end
+
+      def format(request, collector)
+        total = collector.elapsed_ms.to_f
+        lines = [header_line(request, collector)] + detail_rows(collector, total)
+        lines.join("\n")
+      end
+
+      private
+
+      def detail_rows(collector, total)
+        return tiered_rows(collector, total) if collector.action_duration_ms.positive?
+
+        flat_rows(collector, total)
+      end
+
+      def tiered_rows(collector, total)
+        [
+          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)
+        ]
+      end
+
+      def flat_rows(collector, total)
+        [
+          row("  ", "sql",   collector.sql_duration_ms,   total, :sql),
+          row("  ", "cache", collector.cache_duration_ms, total, :cache)
+        ]
+      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}"
+        return line unless colorize?
+
+        "#{COLORS[:header]}#{line}#{RESET}"
+      end
+
+      def row(indent, label, duration_ms, total_ms, color_key)
+        ms = duration_ms.round
+        bar = colorized_bar(duration_ms, total_ms, color_key)
+        "#{indent}#{label.ljust(11)}#{ms.to_s.rjust(4)}ms #{bar}"
+      end
+
+      def colorized_bar(duration_ms, total_ms, color_key)
+        width = total_ms.positive? ? ((duration_ms.to_f / total_ms) * BAR_WIDTH).round : 0
+        bar = BAR_CHAR * width
+        return bar unless colorize? && width.positive?
+
+        "#{COLORS[color_key]}#{bar}#{RESET}"
+      end
+
+      def colorize?
+        @colorize
+      end
+    end
+  end
+end

data/lib/request_trail/subscriber.rb

@@ -5,9 +5,10 @@ module RequestTrail
     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 ||= [sql_subscription, cache_read_subscription, cache_write_subscription]
+      @attach ||= [sql_subscription, cache_read_subscription, cache_write_subscription, action_subscription]
     end
 
     def self.detach
@@ -40,5 +41,15 @@ module RequestTrail
         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.2.0"
+  VERSION = "0.4.0"
 end

data/lib/request_trail.rb

@@ -5,6 +5,7 @@ require_relative "request_trail/configuration"
 require_relative "request_trail/collector"
 require_relative "request_trail/subscriber"
 require_relative "request_trail/formatter"
+require_relative "request_trail/formatters/flame_graph"
 require_relative "request_trail/middleware"
 require_relative "request_trail/railtie" if defined?(Rails::Railtie)
 
@@ -21,12 +22,11 @@ module RequestTrail
     end
 
     def formatter
-      @formatter ||= Formatter.new
+      configuration.formatter
     end
 
     def reset!
       @configuration = nil
-      @formatter = nil
     end
   end
 end

data/sig/request_trail/collector.rbs

@@ -9,6 +9,8 @@ module RequestTrail
     @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
@@ -16,6 +18,8 @@ module RequestTrail
     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
@@ -25,6 +29,7 @@ module RequestTrail
     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

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

data/sig/request_trail/formatter.rbs

@@ -1,5 +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/formatters/flame_graph.rbs

@@ -0,0 +1,23 @@
+module RequestTrail
+  module Formatters
+    class FlameGraph
+      BAR_WIDTH: Integer
+      BAR_CHAR: String
+      COLORS: Hash[Symbol, String]
+      RESET: String
+
+      def initialize: (?colorize: bool) -> void
+      def format: (::Rack::Request request, Collector collector) -> String
+
+      private
+
+      def detail_rows: (Collector collector, Float total) -> Array[String]
+      def tiered_rows: (Collector collector, Float total) -> Array[String]
+      def flat_rows: (Collector collector, Float total) -> Array[String]
+      def header_line: (::Rack::Request request, Collector collector) -> String
+      def row: (String indent, String label, Float duration_ms, Float total_ms, Symbol color_key) -> String
+      def colorized_bar: (Float duration_ms, Float total_ms, Symbol color_key) -> String
+      def colorize?: () -> bool
+    end
+  end
+end

data/sig/request_trail/subscriber.rbs

@@ -3,6 +3,7 @@ module RequestTrail
     SQL_EVENT: String
     CACHE_READ_EVENT: String
     CACHE_WRITE_EVENT: String
+    ACTION_EVENT: String
 
     self.@attach: Array[untyped]?
 
@@ -14,5 +15,6 @@ module RequestTrail
     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.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -58,6 +58,7 @@ files:
 - lib/request_trail/collector.rb
 - lib/request_trail/configuration.rb
 - lib/request_trail/formatter.rb
+- lib/request_trail/formatters/flame_graph.rb
 - lib/request_trail/middleware.rb
 - lib/request_trail/railtie.rb
 - lib/request_trail/subscriber.rb
@@ -66,6 +67,7 @@ files:
 - sig/request_trail/collector.rbs
 - sig/request_trail/configuration.rbs
 - sig/request_trail/formatter.rbs
+- sig/request_trail/formatters/flame_graph.rbs
 - sig/request_trail/middleware.rbs
 - sig/request_trail/subscriber.rbs
 homepage: https://github.com/eclectic-coding/request-trail