request_trail 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad0751f86ff717630ea62f478707c758fc9d45540721c54016a55e19c86030be
-  data.tar.gz: 6192f331657a761ee7d537c29ded481629cfedfb1da74eb819e9181677010036
+  metadata.gz: b098702d0968a3cfbdc8b4147ab87bae1d24854a32d82b604993d17c75d367ba
+  data.tar.gz: 3a8b148a3a2eb1f7d23f938fbf2b6a70d4776c97a003bacd7ac3fd55989b3c16
 SHA512:
-  metadata.gz: 45d23c714ab2cebe3d5d33db4e8832301e69e496d3cd27419c370eef734bf8581c7d9f815485ab595acf7ce95d9c82c07d580eca805386526edbcd21bfffc74b
-  data.tar.gz: da3154bce7516976fdbff6437b877d639cf9b235a3308cb7101462d63e368b5b64530b932f101975f785cbb18365448e0ef18fbad84c2a5e2d8a3c9db126249c
+  metadata.gz: 4c3bd3e29cae157cce0bdf0f3a3aa243abc0e01bc830f7891f8c0604665246d77cbdc055e693a6f9919c4f788ee2bc9ba5e64739f26c4decd8c3a917e73a3ebe
+  data.tar.gz: f68396f353c7e5ff0debf97ead1ea725e3163a014525f7837bc62774d253872955bd6f6e3c9d82b97e20d88bea3d2f58104a46b74c314b31902d68fb4ac16cc1

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-06-13
+
+### Added
+
+- `config.ignore_paths` — skip tracing for specific paths; accepts strings (exact match) or regexes (e.g. `["/health", /^\/assets/]`)
+- `config.sample_rate` — trace only N% of requests; accepts a float between `0.0` and `1.0` (default `1.0` = 100%)
+- `RequestTrail::Formatters::Base` — mixin that documents the formatter duck-type contract; include it in custom formatters and implement `#format(request, collector) -> String`
+- `FlameGraph` colour overrides — pass `colors: { controller: "\e[36m" }` to `FlameGraph.new` to replace per-layer ANSI codes; unspecified layers keep their defaults
+- Rails install generator — run `rails generate request_trail:install` to scaffold `config/initializers/request_trail.rb` pre-populated with all options and their defaults
+
 ## [0.4.0] - 2026-06-12
 
 ### Added
@@ -40,7 +50,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.4.0...HEAD
+[Unreleased]: https://github.com/eclectic-coding/request-trail/compare/v0.5.0...HEAD
+[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
 [0.2.0]: https://github.com/eclectic-coding/request-trail/releases/tag/v0.2.0

data/README.md

@@ -12,6 +12,7 @@ Middleware that traces a request through all the layers (middleware, controller,
 
 - [Installation](#installation)
 - [Usage](#usage)
+- [Custom formatters](#custom-formatters)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -76,6 +77,49 @@ Output (with ANSI colour when stdout is a TTY):
 
 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).
 
+Override any layer's ANSI code with the `colors:` option:
+
+```ruby
+RequestTrail::Formatters::FlameGraph.new(
+  colorize: true,
+  colors: { controller: "\e[36m", sql: "\e[31m" }
+)
+```
+
+Unspecified layers keep their defaults.
+
+### 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:
+
+```ruby
+class MyFormatter
+  include RequestTrail::Formatters::Base
+
+  def format(request, collector)
+    "#{request.request_method} #{request.path} took #{collector.elapsed_ms.round}ms"
+  end
+end
+
+RequestTrail.configure do |config|
+  config.formatter = MyFormatter.new
+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`
+
+### Installation generator
+
+Run the generator to scaffold the initializer:
+
+```bash
+rails generate request_trail:install
+```
+
+This creates `config/initializers/request_trail.rb` pre-populated with all available options and their defaults.
+
 ### Configuration
 
 Add an initializer to customize behavior:
@@ -88,6 +132,12 @@ RequestTrail.configure do |config|
   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/]
+
+  # trace only N% of requests — useful in high-traffic production environments
+  config.sample_rate   = 0.1      # 0.0 = never, 1.0 = always (default)
 end
 ```
 

data/ROADMAP.md

@@ -2,15 +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.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
 
 - JSON formatter for log aggregators (Datadog, Splunk, etc.)

data/lib/generators/request_trail/install/install_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+return unless defined?(Rails::Generators)
+
+require "rails/generators"
+
+module RequestTrail
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Creates a RequestTrail initializer in config/initializers"
+
+      def copy_initializer
+        template "request_trail.rb.tt", "config/initializers/request_trail.rb"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+RequestTrail.configure do |config|
+  config.enabled      = true    # set to false to disable entirely
+  config.log_level    = :info   # :debug, :info, :warn
+  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.logger    = Rails.logger  # defaults to Rails.logger
+  # config.formatter = RequestTrail::Formatters::FlameGraph.new(colorize: true)
+end

data/lib/request_trail/configuration.rb

@@ -5,12 +5,22 @@ require "logger"
 module RequestTrail
   class Configuration
     attr_writer :logger, :formatter
-    attr_accessor :enabled, :log_level, :threshold_ms
+    attr_accessor :enabled, :log_level, :threshold_ms, :ignore_paths, :sample_rate
 
     def initialize
       @enabled = true
       @log_level = :info
       @threshold_ms = 0
+      @ignore_paths = []
+      @sample_rate = 1.0
+    end
+
+    def sampled?
+      rand < sample_rate
+    end
+
+    def ignored_path?(path)
+      ignore_paths.any? { |pattern| path_matches?(pattern, path) }
     end
 
     def logger
@@ -23,6 +33,13 @@ module RequestTrail
 
     private
 
+    def path_matches?(pattern, path)
+      case pattern
+      when Regexp then pattern.match?(path)
+      else pattern == path
+      end
+    end
+
     def rails_logger
       Rails.logger if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
     end

data/lib/request_trail/formatter.rb

@@ -2,6 +2,8 @@
 
 module RequestTrail
   class Formatter
+    include Formatters::Base
+
     def format(request, collector)
       header = "[RequestTrail] #{request.request_method} #{request.path} #{collector.elapsed_ms.round}ms"
       return tiered_format(header, collector) if collector.action_duration_ms.positive?

data/lib/request_trail/formatters/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RequestTrail
+  module Formatters
+    # Mixin that documents the formatter duck-type contract.
+    # Include it in custom formatters to make the interface explicit;
+    # the only required method is #format(request, collector) -> String.
+    module Base
+      # @param request  [Rack::Request]
+      # @param collector [RequestTrail::Collector]
+      # @return [String] the log line(s) to emit
+      def format(_request, _collector)
+        raise NotImplementedError, "#{self.class}#format must return a String"
+      end
+    end
+  end
+end

data/lib/request_trail/formatters/flame_graph.rb

@@ -3,6 +3,8 @@
 module RequestTrail
   module Formatters
     class FlameGraph
+      include Base
+
       BAR_WIDTH = 36
       BAR_CHAR  = "█"
 
@@ -15,8 +17,9 @@ module RequestTrail
       }.freeze
       RESET = "\e[0m"
 
-      def initialize(colorize: false)
+      def initialize(colorize: false, colors: {})
         @colorize = colorize
+        @colors = COLORS.merge(colors)
       end
 
       def format(request, collector)
@@ -55,7 +58,7 @@ module RequestTrail
         line = "[RequestTrail] #{request.request_method} #{request.path} #{elapsed}ms #{bar}"
         return line unless colorize?
 
-        "#{COLORS[:header]}#{line}#{RESET}"
+        "#{@colors[:header]}#{line}#{RESET}"
       end
 
       def row(indent, label, duration_ms, total_ms, color_key)
@@ -69,7 +72,7 @@ module RequestTrail
         bar = BAR_CHAR * width
         return bar unless colorize? && width.positive?
 
-        "#{COLORS[color_key]}#{bar}#{RESET}"
+        "#{@colors[color_key]}#{bar}#{RESET}"
       end
 
       def colorize?

data/lib/request_trail/middleware.rb

@@ -8,6 +8,8 @@ module RequestTrail
 
     def call(env)
       return @app.call(env) unless RequestTrail.configuration.enabled
+      return @app.call(env) if RequestTrail.configuration.ignored_path?(env["PATH_INFO"])
+      return @app.call(env) unless RequestTrail.configuration.sampled?
 
       Collector.start
       response = @app.call(env)

data/lib/request_trail/version.rb

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

data/lib/request_trail.rb

@@ -4,6 +4,7 @@ require_relative "request_trail/version"
 require_relative "request_trail/configuration"
 require_relative "request_trail/collector"
 require_relative "request_trail/subscriber"
+require_relative "request_trail/formatters/base"
 require_relative "request_trail/formatter"
 require_relative "request_trail/formatters/flame_graph"
 require_relative "request_trail/middleware"

data/sig/request_trail/configuration.rbs

@@ -1,13 +1,17 @@
 module RequestTrail
   class Configuration
     attr_writer logger: ::Logger
-    attr_writer formatter: untyped
+    attr_writer formatter: Formatters::Base
     attr_accessor enabled: bool
     attr_accessor log_level: Symbol
     attr_accessor threshold_ms: Numeric
+    attr_accessor ignore_paths: Array[String | Regexp]
+    attr_accessor sample_rate: Float
 
     def initialize: () -> void
     def logger: () -> ::Logger
-    def formatter: () -> untyped
+    def formatter: () -> Formatters::Base
+    def ignored_path?: (String path) -> bool
+    def sampled?: () -> bool
   end
 end

data/sig/request_trail/formatters/base.rbs

@@ -0,0 +1,7 @@
+module RequestTrail
+  module Formatters
+    module Base
+      def format: (::Rack::Request request, Collector collector) -> String
+    end
+  end
+end

data/sig/request_trail/formatters/flame_graph.rbs

@@ -6,7 +6,7 @@ module RequestTrail
       COLORS: Hash[Symbol, String]
       RESET: String
 
-      def initialize: (?colorize: bool) -> void
+      def initialize: (?colorize: bool, ?colors: Hash[Symbol, String]) -> void
       def format: (::Rack::Request request, Collector collector) -> String
 
       private

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: request_trail
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -54,10 +54,13 @@ files:
 - ROADMAP.md
 - Rakefile
 - codecov.yml
+- 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/collector.rb
 - lib/request_trail/configuration.rb
 - lib/request_trail/formatter.rb
+- lib/request_trail/formatters/base.rb
 - lib/request_trail/formatters/flame_graph.rb
 - lib/request_trail/middleware.rb
 - lib/request_trail/railtie.rb
@@ -67,6 +70,7 @@ files:
 - sig/request_trail/collector.rbs
 - sig/request_trail/configuration.rbs
 - sig/request_trail/formatter.rbs
+- sig/request_trail/formatters/base.rbs
 - sig/request_trail/formatters/flame_graph.rbs
 - sig/request_trail/middleware.rbs
 - sig/request_trail/subscriber.rbs