rails_console_benchmark 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eff8a0cf6f62a6eaf060b7cca6386779d5c2aedc2aa967c1744d554ae124a8a0
+  data.tar.gz: 142bbb22aed8be2063ec44aceaf00a6a9c98feb33a08ff4f3210d761525899a6
+SHA512:
+  metadata.gz: 6d788649e3172dda31d50ef231bf65fddc081ac5c79e3d4b25dc32ab512d0b0053df189b50bf82f258e10e79ddef3c17dc48b931d2c5f3d37f2b99fe1b6098c1
+  data.tar.gz: 0d933f576411d45282a1e4660920915086d2edf6316d956b8e04a507dfd903d67ade2d45009c2b1ee03dcbac17428524996f5e8be061aa2d8a3e61326911676c

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+## [Unreleased]
+
+## [0.0.1] - 2026-03-26
+
+### Added
+
+- `Tracker.measure` for profiling a block of Ruby/Rails code.
+- Wall time measurement via `Process.clock_gettime(Process::CLOCK_MONOTONIC)`, reported in milliseconds (3 decimal places).
+- SQL query count tracking via `ActiveSupport::Notifications` (Rails-optional; skips `SCHEMA` and `CACHE` queries).
+- Memory allocation and retention profiling via `memory_profiler` (first iteration only).
+- Results displayed as a formatted terminal table via `terminal-table`.
+- Multi-iteration support: pass an integer to `Tracker.measure(n)` to run the block N times and display min/max/mean/total statistics.
+- Full RSpec test suite covering `Tracker` and `Formatter`, including Rails-optional and non-Rails code paths.
+- SimpleCov test coverage reporting.
+- RuboCop integration (with `rubocop-rake` and `rubocop-rspec`) for code style and quality enforcement.
+- Full RBS type signatures for `Tracker` and `Formatter` in `sig/rails_console_benchmark.rbs`.
+- `Formatter` displays `N/A` for SQL Queries when `ActiveSupport::Notifications` is not available.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"rails_console_benchmark" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["matty.jacques@proton.me"](mailto:"matty.jacques@proton.me").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Matthew Jacques
+
+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,112 @@
+# RailsConsoleBenchmark
+
+A Ruby gem for profiling a block of code from the Rails (or plain Ruby) console. It measures wall time, SQL query count, and memory allocation, then displays the results in a formatted terminal table.
+
+## Features
+
+- **Wall time** — measured via `Process.clock_gettime(Process::CLOCK_MONOTONIC)`, reported in milliseconds (3 decimal places).
+- **SQL query count** — tracked via `ActiveSupport::Notifications` when ActiveRecord is present. `SCHEMA` and `CACHE` queries are excluded.
+- **Memory allocation** — total allocated and retained memory reported via `memory_profiler`. Memory profiling runs on the first iteration only.
+- **Multi-iteration support** — run the block N times and get min/max/mean/total statistics.
+- **Rails-optional** — works in plain Ruby projects with no ActiveRecord dependency.
+
+## Installation
+
+Add to your application's Gemfile:
+
+```bash
+bundle add rails_console_benchmark
+```
+
+Or install directly:
+
+```bash
+gem install rails_console_benchmark
+```
+
+## Usage
+
+### Single run
+
+```ruby
+RailsConsoleBenchmark::Tracker.measure do
+  MyModel.where(active: true).to_a
+end
+```
+
+Example output:
+
+```
++------------------+------------+
+| Metric           | Value      |
++------------------+------------+
+| Wall Time (ms)   | 42.371     |
+| SQL Queries      | 1          |
+| Allocated Memory | 512.00 KB  |
+| Retained Memory  | 4.00 KB    |
++------------------+------------+
+```
+
+### Multiple iterations
+
+```ruby
+RailsConsoleBenchmark::Tracker.measure(10) do
+  MyModel.where(active: true).to_a
+end
+```
+
+Example output:
+
+```
++------------------+--------+--------+---------+---------+
+| Metric           | Min    | Max    | Mean    | Total   |
++------------------+--------+--------+---------+---------+
+| Wall Time (ms)   | 38.112 | 56.903 | 44.210  | 442.100 |
+| SQL Queries      | 1      | 1      | 1.0     | 10      |
+| Allocated Memory | 512.00 KB | 512.00 KB | 512.00 KB | 512.00 KB |
+| Retained Memory  | 4.00 KB   | 4.00 KB   | 4.00 KB   | 4.00 KB   |
++------------------+--------+--------+---------+---------+
+```
+
+> Memory figures are from the first iteration only, so min/max/mean/total all show the same value.
+
+### Without Rails / ActiveRecord
+
+When `ActiveSupport::Notifications` is not defined, the SQL Queries row displays `N/A`.
+
+## Requirements
+
+- Ruby >= 3.2.0
+- [`memory_profiler`](https://github.com/SamSaffron/memory_profiler) `~> 1.0`
+- [`terminal-table`](https://github.com/tj/terminal-table) `~> 3.0`
+- Rails / ActiveRecord is **optional**
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run `rake spec` to run the test suite. You can also run `bin/console` for an interactive prompt.
+
+To install the gem locally:
+
+```bash
+bundle exec rake install
+```
+
+To release a new version, update `VERSION` in `version.rb` and run:
+
+```bash
+bundle exec rake release
+```
+
+This creates a git tag, pushes commits and the tag, and publishes the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/MattyJacques/rails_console_benchmark. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/MattyJacques/rails_console_benchmark/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the RailsConsoleBenchmark project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/MattyJacques/rails_console_benchmark/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/rails_console_benchmark/formatter.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'terminal-table'
+
+module RailsConsoleBenchmark
+  # Formats and displays benchmark results as a table in the console.
+  module Formatter
+    class << self
+      def display(result)
+        wall_times = result[:wall_times_ms]
+        headings, rows = wall_times.length == 1 ? single_result(result) : aggregate_result(result)
+        puts Terminal::Table.new(headings: headings, rows: rows)
+      end
+
+      private
+
+      def single_result(result)
+        rows = [
+          ['Wall Time (ms)', result[:wall_times_ms].first],
+          sql_row(result[:sql_queries], single: true),
+          ['Allocated Memory', format_bytes(result[:allocated_memory])],
+          ['Retained Memory', format_bytes(result[:retained_memory])]
+        ]
+        [%w[Metric Value], rows]
+      end
+
+      def aggregate_result(result)
+        rows = [
+          aggregate_row('Wall Time (ms)', result[:wall_times_ms]),
+          sql_row(result[:sql_queries]),
+          memory_row('Allocated Memory', result[:allocated_memory]),
+          memory_row('Retained Memory', result[:retained_memory])
+        ]
+        [%w[Metric Min Max Mean Total], rows]
+      end
+
+      def sql_row(sql_queries, single: false)
+        if sql_queries.nil?
+          single ? ['SQL Queries', 'N/A'] : ['SQL Queries', *(['N/A'] * 4)]
+        elsif single
+          ['SQL Queries', sql_queries.first]
+        else
+          aggregate_row('SQL Queries', sql_queries)
+        end
+      end
+
+      def aggregate_row(label, values)
+        total = values.sum
+        [
+          label,
+          values.min,
+          values.max,
+          (total.to_f / values.length).round(3),
+          total.round(3)
+        ]
+      end
+
+      def memory_row(label, bytes)
+        formatted = format_bytes(bytes)
+        [label, *([formatted] * 4)]
+      end
+
+      def format_bytes(bytes)
+        return '0 B' if bytes.zero?
+
+        units = %w[B KB MB GB]
+        exp = (Math.log(bytes) / Math.log(1024)).floor
+        exp = [exp, units.length - 1].min
+        format('%<value>.2f %<unit>s', value: bytes.to_f / (1024**exp), unit: units[exp])
+      end
+    end
+  end
+end

data/lib/rails_console_benchmark/tracker.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'memory_profiler'
+
+module RailsConsoleBenchmark
+  # Measures wall time, SQL query counts, and memory usage for a block of code.
+  class Tracker
+    def self.measure(iterations = 1, &)
+      new(iterations).measure(&)
+    end
+
+    def initialize(iterations = 1)
+      raise ArgumentError, 'iterations must be >= 1' if iterations < 1
+
+      @iterations = iterations
+      @track_sql = defined?(ActiveSupport::Notifications)
+    end
+
+    def measure(&)
+      wall_times, sql_counts, memory_report = collect_measurements(&)
+      RailsConsoleBenchmark::Formatter.display(
+        wall_times_ms: wall_times,
+        sql_queries: sql_counts,
+        allocated_memory: memory_report.total_allocated_memsize,
+        retained_memory: memory_report.total_retained_memsize
+      )
+    end
+
+    private
+
+    def collect_measurements(&block)
+      results = (0...@iterations).map { |i| run_iteration(i, &block) }
+      [wall_times(results), sql_counts(results), memory_report(results)]
+    end
+
+    def wall_times(results)
+      results.map { |wt, *| (wt * 1000).round(3) }
+    end
+
+    def sql_counts(results)
+      @track_sql ? results.map { |_wt, sql, *| sql } : nil
+    end
+
+    def memory_report(results)
+      results.first.last
+    end
+
+    def run_iteration(index, &block)
+      result, sql_count = with_sql_tracking do
+        if index.zero?
+          timed_with_memory_profile { start_time_and_call(&block) }
+        else
+          [start_time_and_call(&block), nil]
+        end
+      end
+      wall_time, report = result
+      [wall_time, sql_count, report]
+    end
+
+    def with_sql_tracking(&block)
+      return [block.call, nil] unless @track_sql
+
+      sql_count = 0
+      subscriber = lambda { |*, payload|
+        next if payload[:name]&.start_with?('SCHEMA', 'CACHE')
+
+        sql_count += 1
+      }
+      result = ActiveSupport::Notifications.subscribed(subscriber, 'sql.active_record', &block)
+      [result, sql_count]
+    end
+
+    def timed_with_memory_profile(&block)
+      wall_time = nil
+      report = MemoryProfiler.report { wall_time = block.call }
+      [wall_time, report]
+    end
+
+    def start_time_and_call(&block)
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      block.call
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+    end
+  end
+end

data/lib/rails_console_benchmark/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsConsoleBenchmark
+  VERSION = '0.0.1'
+end

data/lib/rails_console_benchmark.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'rails_console_benchmark/version'
+require_relative 'rails_console_benchmark/formatter'
+require_relative 'rails_console_benchmark/tracker'
+
+# Top-level namespace for the RailsConsoleBenchmark gem.
+module RailsConsoleBenchmark
+end

data/sig/rails_console_benchmark.rbs

@@ -0,0 +1,33 @@
+module RailsConsoleBenchmark
+  VERSION: String
+
+  class Tracker
+    def self.measure: (?::Integer iterations) { () -> untyped } -> void
+
+    def initialize: (?::Integer iterations) -> void
+
+    def measure: () { () -> untyped } -> void
+
+    private
+
+    def collect_measurements: () { () -> untyped } -> [Array[Float], Array[Integer]?, untyped]
+
+    def wall_times: (Array[[Float, untyped, untyped]]) -> Array[Float]
+
+    def sql_counts: (Array[[Float, Integer?, untyped]]) -> Array[Integer]?
+
+    def memory_report: (Array[[Float, untyped, untyped]]) -> untyped
+
+    def run_iteration: (::Integer index) { () -> untyped } -> [Float, Integer?, untyped]
+
+    def with_sql_tracking: () { () -> untyped } -> [untyped, Integer?]
+
+    def timed_with_memory_profile: () { () -> untyped } -> [Float, untyped]
+
+    def start_time_and_call: () { () -> untyped } -> Float
+  end
+
+  module Formatter
+    def self.display: ({ wall_times_ms: Array[Float], sql_queries: Array[Integer]?, allocated_memory: Integer, retained_memory: Integer }) -> void
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: rails_console_benchmark
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Matthew Jacques
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: memory_profiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: terminal-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A gem that measures block execution time, database query counts (when
+  ActiveRecord is present), and memory allocation, displaying results in a formatted
+  terminal table. Works in plain Ruby and Rails projects alike.
+email:
+- matty.jacques@proton.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/rails_console_benchmark.rb
+- lib/rails_console_benchmark/formatter.rb
+- lib/rails_console_benchmark/tracker.rb
+- lib/rails_console_benchmark/version.rb
+- sig/rails_console_benchmark.rbs
+homepage: https://github.com/MattyJacques/rails_console_benchmark
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/MattyJacques/rails_console_benchmark
+  source_code_uri: https://github.com/MattyJacques/rails_console_benchmark
+  changelog_uri: https://github.com/MattyJacques/rails_console_benchmark/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.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.8
+specification_version: 4
+summary: 'Profile Ruby/Rails console block execution: wall time, SQL query count,
+  and memory usage.'
+test_files: []