request_trail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ef1bf3bfcc191f502a9380fbe03bcdba11db1003b6b061db77b93769ac8697ba
+  data.tar.gz: 6df870ef886ee153cda6babf4cb75c2d80484c9d42c61fccd926fe5278a42705
+SHA512:
+  metadata.gz: 484a485f9ffd159c6daf55abd72f9dc44204d483b2ed31242e502433224c7adf59b33a211e1fd501d703437caa1c4158775b463f0c3c4cdd7156283078ed3b89
+  data.tar.gz: 99d772953da1f97dea448fb3e50bf8889c7a1e29fae0a67805e210d949cddbacad5e039bd7d59821480109c6a62566e73d3575d21a0f61badf3c19e5eec08731

data/.github/workflows/main.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Run RuboCop
+        run: bundle exec rubocop
+
+  security:
+    name: Security audit
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Run bundler-audit
+        run: bundle exec rake bundle:audit:update bundle:audit:check
+
+  test:
+    name: Ruby ${{ matrix.ruby }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - "3.3"
+          - "3.4"
+          - "4.0"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run test suite
+        run: bundle exec rake spec
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v7
+        if: matrix.ruby == '3.4'
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage/coverage.json

data/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  publish:
+    name: Publish to RubyGems
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: Run test suite
+        run: bundle exec rake
+
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${{ github.ref_name }}" \
+            --title "${{ github.ref_name }}" \
+            --notes "See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details." \
+            --verify-tag
+
+      - name: Publish to RubyGems
+        uses: rubygems/release-gem@v1

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-11
+
+### Added
+
+- Rack middleware (`RequestTrail::Middleware`) that wraps requests and records wall-clock duration
+- Rails Railtie (`RequestTrail::Railtie`) for automatic middleware insertion
+- ActiveRecord query tracing via `sql.active_record` notifications — records query count and cumulative duration per request
+- Configuration DSL: `RequestTrail.configure { |c| c.enabled = true; c.log_level = :info; c.threshold_ms = 0; c.logger = nil }`
+- Plain-text log formatter producing summaries like `[RequestTrail] GET /orders 142ms | SQL: 7 queries / 38ms`
+- `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
+[0.1.0]: https://github.com/eclectic-coding/request-trail/releases/tag/v0.1.0

data/CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`request_trail` is a Ruby gem (module `RequestTrail`) that traces a Rails request through all processing layers and dumps a flame-graph-style summary to the log.
+
+## Commands
+
+```bash
+bin/setup               # Install dependencies
+bundle exec rake        # Full CI suite: bundler-audit + rubocop + rspec (default task)
+bundle exec rake spec   # Run tests only
+bundle exec rake rubocop # Lint only
+bundle exec rake rubocop:autocorrect # Auto-fix lint violations
+bundle exec rake bundle:audit:update bundle:audit:check # Security audit
+bundle exec rspec spec/path/to/file_spec.rb # Run a single spec file
+bundle exec rspec spec/path/to/file_spec.rb:42 # Run a single example by line
+bin/console             # Interactive prompt with gem loaded
+```
+
+## Architecture
+
+```
+lib/
+  request_trail.rb          # Entry point — RequestTrail module, configure/formatter/reset!
+  request_trail/
+    version.rb              # VERSION constant
+    configuration.rb        # Config object (enabled, log_level, threshold_ms, logger)
+    collector.rb            # Per-request event accumulator (Thread.current storage)
+    subscriber.rb           # ActiveSupport::Notifications subscriber for sql.active_record
+    formatter.rb            # Plain-text log formatter
+    middleware.rb           # Rack middleware — wraps request, drives collector lifecycle
+    railtie.rb              # Rails Railtie — auto-inserts middleware, attaches subscriber
+spec/
+  request_trail_spec.rb     # Main module spec
+  request_trail/            # Per-class specs
+  spec_helper.rb            # Configures SimpleCov (HTML + JSON), loads rack/activesupport/railties
+```
+
+## Code Style
+
+- RuboCop targets Ruby 3.3; `NewCops: enable` means all new cops are active
+- String literals must use **double quotes** (both regular strings and interpolation)
+- `spec/**/*` and `vendor/**/*` are excluded from RuboCop
+- All files use `# frozen_string_literal: true`
+- `Style/Documentation` is disabled — internal classes do not require doc comments
+
+## CI
+
+The GitHub Actions CI (`.github/workflows/main.yml`) runs three jobs on push/PR:
+- **Lint**: RuboCop on Ruby 3.3
+- **Security**: bundler-audit
+- **Test**: RSpec matrix across Ruby 3.3, 3.4, and 4.0; coverage uploaded to Codecov from the 3.4 run
+
+Releases are triggered by `v*` tags via `.github/workflows/publish.yml`, which verifies the tag matches `VERSION`, runs the full suite, builds the gem, and pushes to RubyGems using trusted publishing.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Chuck Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,92 @@
+# RequestTrail
+
+[![CI](https://github.com/eclectic-coding/request-trail/actions/workflows/main.yml/badge.svg)](https://github.com/eclectic-coding/request-trail/actions/workflows/main.yml)
+[![Gem Version](https://img.shields.io/gem/v/request_trail.svg)](https://rubygems.org/gems/request_trail)
+[![Downloads](https://img.shields.io/gem/dt/request_trail.svg)](https://rubygems.org/gems/request_trail)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.3-CC342D.svg)](https://rubygems.org/gems/request_trail)
+[![codecov](https://codecov.io/gh/eclectic-coding/request-trail/branch/main/graph/badge.svg)](https://codecov.io/gh/eclectic-coding/request-trail)
+
+Middleware that traces a request through all the layers (middleware, controller, ActiveRecord, cache) and dumps a flame-graph-style summary to the log.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+Add to your application's Gemfile:
+
+```bash
+bundle add request_trail
+```
+
+Or install directly:
+
+```bash
+gem install request_trail
+```
+
+[Back to top](#requesttrail)
+
+## Usage
+
+### 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] GET /orders 142ms | SQL: 7 queries / 38ms
+```
+
+### Configuration
+
+Add an initializer to customize behavior:
+
+```ruby
+# config/initializers/request_trail.rb
+RequestTrail.configure do |config|
+  config.enabled       = true      # set to false to disable entirely
+  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
+end
+```
+
+### Non-Rails (plain Rack)
+
+Insert the middleware manually and attach the subscriber:
+
+```ruby
+require "request_trail"
+
+RequestTrail::Subscriber.attach
+
+use RequestTrail::Middleware
+run MyApp
+```
+
+[Back to top](#requesttrail)
+
+## 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.
+
+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).
+
+[Back to top](#requesttrail)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/eclectic-coding/request-trail.
+
+[Back to top](#requesttrail)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+[Back to top](#requesttrail)

data/ROADMAP.md

@@ -0,0 +1,58 @@
+# Roadmap
+
+`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
+- 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`
+
+## 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)
+- 100% test coverage
+- Overhead benchmark suite (target: < 1ms added latency per request)
+- Full usage documentation with real-world examples

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+require "rspec/core/rake_task"
+require "bundler/audit/task"
+
+RuboCop::RakeTask.new
+RSpec::Core::RakeTask.new(:spec)
+Bundler::Audit::Task.new
+
+desc "Run bundler-audit, rubocop, and rspec (full CI suite)"
+task default: ["bundle:audit:update", "bundle:audit:check", :rubocop, :spec]

data/codecov.yml

@@ -0,0 +1,14 @@
+comment:
+  layout: "reach, diff, flags, files"
+  behavior: default
+  # Only post or update the comment if the coverage drops
+  require_changes: "coverage_drop"
+
+coverage:
+  status:
+    project:
+      default:
+        informational: false
+    patch:
+      default:
+        informational: false

data/lib/request_trail/collector.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RequestTrail
+  class Collector
+    THREAD_KEY = :request_trail_collector
+
+    attr_reader :sql_count, :sql_duration_ms
+
+    def self.current
+      Thread.current[THREAD_KEY]
+    end
+
+    def self.start
+      Thread.current[THREAD_KEY] = new
+    end
+
+    def self.stop
+      Thread.current[THREAD_KEY] = nil
+    end
+
+    def initialize
+      @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @sql_count = 0
+      @sql_duration_ms = 0.0
+    end
+
+    def record_sql(duration_ms)
+      @sql_count += 1
+      @sql_duration_ms += duration_ms
+    end
+
+    def elapsed_ms
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at
+      (elapsed * 1000).round(2)
+    end
+  end
+end

data/lib/request_trail/configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module RequestTrail
+  class Configuration
+    attr_writer :logger
+    attr_accessor :enabled, :log_level, :threshold_ms
+
+    def initialize
+      @enabled = true
+      @log_level = :info
+      @threshold_ms = 0
+    end
+
+    def logger
+      @logger ||= rails_logger || Logger.new($stdout)
+    end
+
+    private
+
+    def rails_logger
+      Rails.logger if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+    end
+  end
+end

data/lib/request_trail/formatter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RequestTrail
+  class Formatter
+    def format(request, collector)
+      header = "[RequestTrail] #{request.request_method} #{request.path}"
+      "#{header} #{collector.elapsed_ms.round}ms | #{sql_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"
+    end
+  end
+end

data/lib/request_trail/middleware.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RequestTrail
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      return @app.call(env) unless RequestTrail.configuration.enabled
+
+      Collector.start
+      response = @app.call(env)
+      log(env)
+      response
+    ensure
+      Collector.stop
+    end
+
+    private
+
+    def log(env)
+      collector = Collector.current
+      elapsed = collector.elapsed_ms
+      return if elapsed < RequestTrail.configuration.threshold_ms
+
+      request = Rack::Request.new(env)
+      message = RequestTrail.formatter.format(request, collector)
+      RequestTrail.configuration.logger.send(RequestTrail.configuration.log_level, message)
+    end
+  end
+end

data/lib/request_trail/railtie.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RequestTrail
+  class Railtie < Rails::Railtie
+    # :nocov:
+    initializer "request_trail.insert_middleware" do |app|
+      app.middleware.use(RequestTrail::Middleware)
+      Subscriber.attach
+    end
+    # :nocov:
+  end
+end

data/lib/request_trail/subscriber.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RequestTrail
+  class Subscriber
+    SQL_EVENT = "sql.active_record"
+
+    def self.attach
+      @attach ||= ActiveSupport::Notifications.subscribe(SQL_EVENT) do |*args|
+        event = ActiveSupport::Notifications::Event.new(*args)
+        Collector.current&.record_sql(event.duration)
+      end
+    end
+
+    def self.detach
+      return unless @attach
+
+      ActiveSupport::Notifications.unsubscribe(@attach)
+      @attach = nil
+    end
+  end
+end

data/lib/request_trail/version.rb

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

data/lib/request_trail.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "request_trail/version"
+require_relative "request_trail/configuration"
+require_relative "request_trail/collector"
+require_relative "request_trail/subscriber"
+require_relative "request_trail/formatter"
+require_relative "request_trail/middleware"
+require_relative "request_trail/railtie" if defined?(Rails::Railtie)
+
+module RequestTrail
+  class Error < StandardError; end
+
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def formatter
+      @formatter ||= Formatter.new
+    end
+
+    def reset!
+      @configuration = nil
+      @formatter = nil
+    end
+  end
+end

data/sig/request_trail.rbs

@@ -0,0 +1,3 @@
+module RequestTrail
+  VERSION: String
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: request_trail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chuck Smith
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Middleware that traces a request through middleware, controller, ActiveRecord,
+  and cache layers, then dumps a flame-graph-style summary to the log.
+email:
+- eclectic-coding@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/main.yml"
+- ".github/workflows/publish.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- ROADMAP.md
+- Rakefile
+- codecov.yml
+- lib/request_trail.rb
+- lib/request_trail/collector.rb
+- lib/request_trail/configuration.rb
+- lib/request_trail/formatter.rb
+- lib/request_trail/middleware.rb
+- lib/request_trail/railtie.rb
+- lib/request_trail/subscriber.rb
+- lib/request_trail/version.rb
+- sig/request_trail.rbs
+homepage: https://github.com/eclectic-coding/request-trail
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/eclectic-coding/request-trail
+  source_code_uri: https://github.com/eclectic-coding/request-trail
+  changelog_uri: https://github.com/eclectic-coding/request-trail/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Traces a Rails request through all layers and dumps a flame-graph summary
+  to the log.
+test_files: []