request_trail 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b098702d0968a3cfbdc8b4147ab87bae1d24854a32d82b604993d17c75d367ba
-  data.tar.gz: 3a8b148a3a2eb1f7d23f938fbf2b6a70d4776c97a003bacd7ac3fd55989b3c16
+  metadata.gz: 2c636ff49dd9c5f372269c4e9a9611a7e610e5e5f6f172a951e1f7d76579f804
+  data.tar.gz: 2e7a528107b38f1c3e92d0bc11bbdfd2b51295daaf616f4e6cbb82dbe8cc71e1
 SHA512:
-  metadata.gz: 4c3bd3e29cae157cce0bdf0f3a3aa243abc0e01bc830f7891f8c0604665246d77cbdc055e693a6f9919c4f788ee2bc9ba5e64739f26c4decd8c3a917e73a3ebe
-  data.tar.gz: f68396f353c7e5ff0debf97ead1ea725e3163a014525f7837bc62774d253872955bd6f6e3c9d82b97e20d88bea3d2f58104a46b74c314b31902d68fb4ac16cc1
+  metadata.gz: c4d2694d6a22c9a24884968967cb4210771e12efd1d43934df844dbdf699382ec994e620b0d6f75773b6584c5ae2f4a4c6cd6f346f808c400e70c36603b59352
+  data.tar.gz: f8597a5b458895afa2d09081ba96fd422c971733918f64a2a7109133103e12b0725fdb20d4ec2efc2b7d8a8dca383d241037796b69c10d902b5bd819085a6700

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-06-14
+
+### Added
+
+- `RequestTrail::Formatters::JSON` — structured JSON formatter for log aggregators (Datadog, Splunk, etc.); opt in via `config.formatter = RequestTrail::Formatters::JSON.new`
+- `RequestTrail.log_tag` — callable proc for `config.log_tags`; returns a lazy `LogTag::Value` that evaluates to `sql=N Nms` at log-line time, so every tagged line reflects the live request SQL state
+- `RequestTrail::SidekiqMiddleware` — optional Sidekiq server middleware that traces background job execution with the same flame-graph output; add `chain.add RequestTrail::SidekiqMiddleware` inside `Sidekiq.configure_server` to enable
+
 ## [0.5.0] - 2026-06-13
 
 ### Added

data/README.md

@@ -55,6 +55,28 @@ 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
 ```
 
+### JSON formatter
+
+Emit structured JSON for log aggregators (Datadog, Splunk, etc.):
+
+```ruby
+RequestTrail.configure do |config|
+  config.formatter = RequestTrail::Formatters::JSON.new
+end
+```
+
+Example output (flat request):
+
+```json
+{"method":"GET","path":"/orders","duration_ms":142.5,"sql":{"count":7,"duration_ms":38.0},"cache":{"hits":4,"misses":1,"writes":0,"duration_ms":2.0}}
+```
+
+When controller data is present a `"controller"` key is added:
+
+```json
+{"method":"GET","path":"/orders","duration_ms":142.5,"sql":{"count":7,"duration_ms":38.0},"cache":{"hits":4,"misses":1,"writes":0,"duration_ms":2.0},"controller":{"duration_ms":104.0,"view_duration_ms":22.0}}
+```
+
 ### Flame graph formatter
 
 Opt into the ASCII flame-graph formatter for a visual proportional breakdown:

data/ROADMAP.md

@@ -2,13 +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.6.0 — Structured Output & Integrations
-
-- JSON formatter for log aggregators (Datadog, Splunk, etc.)
-- `config.logger` override for writing to a separate file or custom appender
-- Rails log tags integration
-- Optional Sidekiq adapter for tracing background job execution layers
-
 ## 1.0.0 — Stable Release
 
 - Frozen public API (`Request::Trail.configure`, middleware interface, formatter interface)

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

@@ -9,4 +9,15 @@ RequestTrail.configure do |config|
 
   # config.logger    = Rails.logger  # defaults to Rails.logger
   # config.formatter = RequestTrail::Formatters::FlameGraph.new(colorize: true)
-end
+end
+
+# Rails log tags — add the trail summary to every tagged log line:
+#   config.log_tags = [:request_id, RequestTrail.log_tag]
+
+# Sidekiq — trace background jobs with the same flame-graph output.
+# Add to config/initializers/sidekiq.rb:
+#   Sidekiq.configure_server do |config|
+#     config.server_middleware do |chain|
+#       chain.add RequestTrail::SidekiqMiddleware
+#     end
+#   end

data/lib/request_trail/formatters/json.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RequestTrail
+  module Formatters
+    class JSON
+      include Base
+
+      def format(request, collector)
+        payload = base_payload(request, collector)
+        payload[:controller] = controller_payload(collector) if collector.action_duration_ms.positive?
+        ::JSON.generate(payload)
+      end
+
+      private
+
+      def base_payload(request, collector)
+        {
+          method: request.request_method,
+          path: request.path,
+          duration_ms: collector.elapsed_ms,
+          sql: { count: collector.sql_count, duration_ms: collector.sql_duration_ms },
+          cache: cache_payload(collector)
+        }
+      end
+
+      def cache_payload(collector)
+        {
+          hits: collector.cache_hits,
+          misses: collector.cache_misses,
+          writes: collector.cache_writes,
+          duration_ms: collector.cache_duration_ms
+        }
+      end
+
+      def controller_payload(collector)
+        {
+          duration_ms: collector.action_duration_ms,
+          view_duration_ms: collector.view_duration_ms
+        }
+      end
+    end
+  end
+end

data/lib/request_trail/log_tag.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RequestTrail
+  module LogTag
+    class Value
+      def to_s
+        collector = Collector.current
+        return "" unless collector
+
+        "sql=#{collector.sql_count} #{collector.elapsed_ms.round}ms"
+      end
+
+      def blank?
+        to_s.empty?
+      end
+    end
+  end
+end

data/lib/request_trail/sidekiq_middleware.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RequestTrail
+  class SidekiqMiddleware
+    JobContext = Struct.new(:request_method, :path, keyword_init: true)
+
+    def call(_worker, job, _queue)
+      return yield unless RequestTrail.configuration.enabled
+      return yield unless RequestTrail.configuration.sampled?
+
+      Collector.start
+      yield
+      log(job)
+    ensure
+      Collector.stop
+    end
+
+    private
+
+    def log(job)
+      collector = Collector.current
+      elapsed = collector.elapsed_ms
+      return if elapsed < RequestTrail.configuration.threshold_ms
+
+      context = JobContext.new(
+        request_method: "JOB",
+        path: "#{job["class"]} jid:#{job["jid"]}"
+      )
+      message = RequestTrail.formatter.format(context, collector)
+      RequestTrail.configuration.logger.send(RequestTrail.configuration.log_level, message)
+    end
+  end
+end

data/lib/request_trail/version.rb

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

data/lib/request_trail.rb

@@ -7,7 +7,10 @@ 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/formatters/json"
+require_relative "request_trail/log_tag"
 require_relative "request_trail/middleware"
+require_relative "request_trail/sidekiq_middleware" if defined?(Sidekiq)
 require_relative "request_trail/railtie" if defined?(Rails::Railtie)
 
 module RequestTrail
@@ -26,6 +29,10 @@ module RequestTrail
       configuration.formatter
     end
 
+    def log_tag
+      ->(_request) { LogTag::Value.new }
+    end
+
     def reset!
       @configuration = nil
     end

data/sig/request_trail/formatter.rbs

@@ -1,6 +1,6 @@
 module RequestTrail
   class Formatter
-    def format: (::Rack::Request request, Collector collector) -> String
+    def format: (_RequestContext request, Collector collector) -> String
 
     private
 

data/sig/request_trail/formatters/base.rbs

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

data/sig/request_trail/formatters/flame_graph.rbs

@@ -7,14 +7,14 @@ module RequestTrail
       RESET: String
 
       def initialize: (?colorize: bool, ?colors: Hash[Symbol, String]) -> void
-      def format: (::Rack::Request request, Collector collector) -> String
+      def format: (_RequestContext 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 header_line: (_RequestContext 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

data/sig/request_trail/formatters/json.rbs

@@ -0,0 +1,15 @@
+module RequestTrail
+  module Formatters
+    class JSON
+      include Base
+
+      def format: (_RequestContext request, Collector collector) -> String
+
+      private
+
+      def base_payload: (_RequestContext request, Collector collector) -> Hash[Symbol, untyped]
+      def cache_payload: (Collector collector) -> Hash[Symbol, untyped]
+      def controller_payload: (Collector collector) -> Hash[Symbol, untyped]
+    end
+  end
+end

data/sig/request_trail/log_tag.rbs

@@ -0,0 +1,8 @@
+module RequestTrail
+  module LogTag
+    class Value
+      def to_s: () -> String
+      def blank?: () -> bool
+    end
+  end
+end

data/sig/request_trail/sidekiq_middleware.rbs

@@ -0,0 +1,12 @@
+module RequestTrail
+  class SidekiqMiddleware
+    class JobContext
+      attr_accessor request_method: String
+      attr_accessor path: String
+
+      def initialize: (request_method: String, path: String) -> void
+    end
+
+    def call: (untyped _worker, Hash[String, untyped] job, untyped _queue) { () -> void } -> void
+  end
+end

data/sig/request_trail.rbs

@@ -1,3 +1,14 @@
 module RequestTrail
   VERSION: String
+
+  interface _RequestContext
+    def request_method: () -> String
+    def path: () -> String
+  end
+
+  def self.configure: () { (Configuration) -> void } -> void
+  def self.configuration: () -> Configuration
+  def self.formatter: () -> Formatters::Base
+  def self.log_tag: () -> ^(untyped) -> LogTag::Value
+  def self.reset!: () -> nil
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: request_trail
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -62,8 +62,11 @@ files:
 - lib/request_trail/formatter.rb
 - lib/request_trail/formatters/base.rb
 - lib/request_trail/formatters/flame_graph.rb
+- lib/request_trail/formatters/json.rb
+- lib/request_trail/log_tag.rb
 - lib/request_trail/middleware.rb
 - lib/request_trail/railtie.rb
+- lib/request_trail/sidekiq_middleware.rb
 - lib/request_trail/subscriber.rb
 - lib/request_trail/version.rb
 - sig/request_trail.rbs
@@ -72,7 +75,10 @@ files:
 - sig/request_trail/formatter.rbs
 - sig/request_trail/formatters/base.rbs
 - sig/request_trail/formatters/flame_graph.rbs
+- sig/request_trail/formatters/json.rbs
+- sig/request_trail/log_tag.rbs
 - sig/request_trail/middleware.rbs
+- sig/request_trail/sidekiq_middleware.rbs
 - sig/request_trail/subscriber.rbs
 homepage: https://github.com/eclectic-coding/request-trail
 licenses: