class-profiler 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3cc114dfe22c12351314f0374fec2f6caa62c781ec643b8ee4b9f8df53d38bb0
+  data.tar.gz: bd6c43d1ce630abf9389a0cc4b4048cc0b09a26e263e9bf6fc240b55de038894
+SHA512:
+  metadata.gz: 132477ca1e6db7f33c42833fac920bb175f1725701932f9b0991ca9895d1f1f176b79a754277c302d81a61da442807ed0c985575471654d5f720f19f0dd538ad
+  data.tar.gz: bd324e3ea404c8256bc1c8e7192d3484e4265fa4f1e2a447e727eedad1a205aeff30729bd8d300570d0f81aac48cccf4156705c3ec2940eaf9801a7130080fba

data/.github/workflows/main.yml

@@ -0,0 +1,27 @@
+name: Ruby
+
+on:
+  push:
+    branches:
+      - main
+
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: Ruby ${{ matrix.ruby }}
+    strategy:
+      matrix:
+        ruby:
+          - '3.2.1'
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - name: Run the default task
+      run: bundle exec rake

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,38 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: single_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*.rb
+    - ./* # for Guardfile, gemspec, etc.
+
+Style/BlockComments:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Layout/LineLength:
+  Enabled: false
+
+Style/AccessModifierDeclarations:
+  EnforcedStyle: inline
+  Enabled: true
+
+Metrics/PerceivedComplexity:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,157 @@
+PATH
+  remote: .
+  specs:
+    class-profiler (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (8.0.2.1)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    ast (2.4.2)
+    base64 (0.3.0)
+    benchmark (0.4.0)
+    bigdecimal (3.2.2)
+    binding_of_caller (1.0.1)
+      debug_inspector (>= 1.2.0)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.4.1)
+    debug_inspector (1.2.0)
+    diff-lcs (1.5.1)
+    drb (2.2.1)
+    ffi (1.17.2-aarch64-linux-gnu)
+    ffi (1.17.2-arm-linux-gnu)
+    ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86-linux-gnu)
+    ffi (1.17.2-x86_64-darwin)
+    ffi (1.17.2-x86_64-linux-gnu)
+    formatador (1.2.0)
+      reline
+    guard (2.19.1)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, < 4.0)
+      logger (~> 1.6)
+      lumberjack (>= 1.0.12, < 2.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      ostruct (~> 0.6)
+      pry (>= 0.13.0)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.7.3)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.1)
+    json (2.10.1)
+    language_server-protocol (3.17.0.4)
+    lint_roller (1.1.0)
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    lumberjack (1.4.1)
+    method_source (1.1.0)
+    minitest (5.25.5)
+    nenv (0.3.0)
+    notiffany (0.1.3)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    ostruct (0.6.3)
+    parallel (1.26.3)
+    parser (3.3.7.1)
+      ast (~> 2.4.1)
+      racc
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
+    pry-stack_explorer (0.6.1)
+      binding_of_caller (~> 1.0)
+      pry (~> 0.13)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    regexp_parser (2.10.0)
+    reline (0.6.2)
+      io-console (~> 0.5)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.0)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    rubocop (1.73.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.38.1)
+      parser (>= 3.3.1.0)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    shellany (0.0.1)
+    thor (1.4.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+    uri (1.0.2)
+
+PLATFORMS
+  aarch64-linux
+  arm-linux
+  arm64-darwin
+  x86-linux
+  x86_64-darwin
+  x86_64-linux
+
+DEPENDENCIES
+  activesupport
+  class-profiler!
+  guard
+  guard-rspec
+  pry
+  pry-byebug
+  pry-stack_explorer
+  rake
+  rspec
+  rubocop
+
+BUNDLED WITH
+   2.5.17

data/Guardfile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  require 'guard/rspec/dsl'
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Matthew Greenfield
+
+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,173 @@
+ClassProfiler: track performance and memory allocations in Ruby classes
+
+### Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'class-profiler'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install class-profiler
+```
+
+### Usage
+
+Include `ClassProfiler` in your class. Use the unified class-level helpers to wrap methods.
+
+```ruby
+class Report
+  include ClassProfiler
+
+  def fetch
+    sleep 0.01
+    'ok'
+  end
+
+  def allocate
+    Array.new(1000) { 'x' * 10 }
+  end
+
+  # Track non-inherited public/protected/private instance methods (default)
+  track_performance
+  track_memory
+end
+
+r = Report.new
+r.fetch
+r.allocate
+
+# Per-method metrics
+r.performance        # => { fetch: { time: 0.0102, total: 0.0306 } }
+r.memory             # => { allocate: { allocated_objects: 1005, malloc_increase_bytes: 8192 } }
+
+# Combined view (performance + memory)
+r.profile            # => { fetch: { time: 0.0102 }, allocate: { objects: 1005, bytes: 8192 } }
+
+# Reports
+r.performance_report # prints a table of last time and total time
+r.memory_report      # prints a table of allocations/bytes
+r.profile_report     # prints a combined table
+```
+
+Selection is controlled via flags on the unified helpers:
+
+```ruby
+# Include inherited methods?
+track_performance inherited: true
+track_memory inherited: true
+
+# Choose visibilities (public/protected/private default to true)
+track_performance protected: false, private: false
+track_memory public: true, protected: false, private: false
+```
+
+### API
+
+- `track_performance(inherited: false, public: true, protected: true, private: true)`
+- `track_memory(inherited: false, public: true, protected: true, private: true)`
+- `performance` (instance): Hash of method name → `{ time: Float, total: Float }`
+- `memory` (instance): Hash of method name → allocation deltas
+  - `allocated_objects` (Integer)
+  - `malloc_increase_bytes` (Integer)
+- `profile` (instance): Combined Hash of method name → `{ time:, objects:, bytes: }`
+- `performance_report`, `memory_report`, `profile_report` (instance): print tabular reports
+
+### Composing with wrap_method
+
+You can compose custom behaviors using the built-in `wrap_method` helper from `ClassProfiler::Methods`.
+This is the same mechanism used by the Performance and Memory modules under the hood.
+
+```ruby
+class Widget
+  include ClassProfiler
+
+  def compute(x, y)
+    x + y
+  end
+
+  # Add custom logging around the original implementation
+  wrap_method :compute do |original, *args|
+    profiler_logger.info("compute called with #{args.inspect}")
+    result = original.bind(self).call(*args)
+    profiler_logger.info("compute returned #{result}")
+    result
+  end
+
+  # You can still benchmark or profile the same method
+  track_performance
+  # track_memory
+end
+
+w = Widget.new
+w.compute(2, 3)
+w.performance[:compute] # => { time:, total: }
+```
+
+### Requirements
+
+- Ruby >= 3.1
+
+### Development
+
+- Run `bin/setup` to install dependencies
+- Run `rake` to execute tests and RuboCop
+- Run `bin/console` to experiment in Pry
+
+### Examples (speed vs memory trade-offs)
+
+Explore the gem with runnable examples that contrast time vs memory usage for common problems.
+
+Run all examples:
+
+```bash
+bundle exec rake examples
+```
+
+What you'll see:
+
+```text
+=== Two Sum: brute_force (low memory, slower) vs hashmap (higher memory, faster) ===
+Input SIZE=5000
+
+Summary (lower time is better; lower allocations usually better):
+Method           Time (s)     Allocated Objects     Malloc +bytes
+----------------------------------------------------------------------
+brute_force      0.456789     12345                 0
+hashmap          0.012345     45678                 8192
+
+Speed: hashmap is 37.00x faster than brute_force
+Memory: hashmap allocates 3.70x more objects than brute_force
+
+Raw reports:
+...
+```
+
+You can run individual examples and tune sizes:
+
+```bash
+# Two Sum: brute force vs hash map
+SIZE=10000 bundle exec ruby examples/two_sum.rb
+
+# Primes: trial division vs sieve of Eratosthenes
+N=50000 bundle exec ruby examples/primes.rb
+```
+
+Each example prints a concise table plus a human-readable conclusion highlighting the trade-off (e.g. "sieve is 10x faster but allocates 4x more objects").
+
+### Contributing
+
+Bug reports and pull requests are welcome on GitHub at `https://github.com/omgreenfield/class-profiler`.
+
+### License
+
+The gem is available as open source under the terms of the MIT License.

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'class_profiler'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require 'pry'
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/class-profiler.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'lib/class_profiler'
+
+Gem::Specification.new do |gem|
+  gem.name = ClassProfiler::NAME
+  gem.version = ClassProfiler::VERSION
+  gem.authors = ['Matthew Greenfield']
+  gem.email = ['mattgreenfield1@gmail.com']
+
+  gem.summary = 'Benchmark speed and profile memory of class methods'
+  gem.description = %(
+    Quickly benchmark execution time and profile memory allocations for specific
+    or all instance methods within a class. Include ClassProfiler to get
+    `benchmark_methods` and `profile_methods` helpers and collect results via
+    `benchmarked` and `profiled_memory`.
+  )
+  gem.homepage = 'https://github.com/omgreenfield/class-profiler'
+  gem.license = 'MIT'
+
+  gem.files = if File.exist?(File.expand_path('.git'))
+                `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec/|examples/)}) }
+              else
+                Dir['lib/**/*.rb'] + Dir['*.md'] + Dir['LICENSE*']
+              end
+  gem.require_paths = ['lib']
+
+  gem.required_ruby_version = '>= 3.1.0'
+
+  gem.add_development_dependency 'activesupport'
+  gem.add_development_dependency 'guard'
+  gem.add_development_dependency 'guard-rspec'
+  gem.add_development_dependency 'pry'
+  gem.add_development_dependency 'pry-byebug'
+  gem.add_development_dependency 'pry-stack_explorer'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'rubocop'
+end

data/config.yml

@@ -0,0 +1,18 @@
+---
+version: 0.1.0
+name: class-profiler
+authors:
+  - Matthew Greenfield
+emails: 
+  - mattgreenfield1@gmail.com
+summary: Quickly benchmark speed and profile memory of specific or all methods within a class
+description: |
+  Quickly benchmark execution time and profile memory allocations for specific or
+  all instance methods within a class. Include ClassProfiler to get helper methods
+  and collect results via `benchmarked` and `profiled_memory`.
+homepage: https://github.com/omgreenfield/class-profiler
+license: MIT
+required_ruby_version: '>= 3.1.0'
+metadata:
+  homepage_uri: https://github.com/omgreenfield/class-profiler
+  rubygems_mfa_required: 'true'

data/lib/class_profiler/logging.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module ClassProfiler
+  module Logging
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(InstanceMethods)
+    end
+
+    module InstanceMethods
+      def profiler_logger
+        self.class.profiler_logger
+      end
+
+      def print_report(entries, headers: [], include_zero: true, sort_index: 0)
+        rows = entries.entries
+        rows.filter! { |(_, time)| include_zero || time.to_f > 0.0 }
+        rows.sort_by! do |row|
+          value = row[sort_index]
+          if value.is_a?(Float)
+            value.to_f
+          else
+            value.to_s
+          end
+        end
+
+        rows = [headers] + rows
+
+        column_widths = rows.transpose.map do |column|
+          column.map { |value| value.to_s.length }.max
+        end
+
+        rows.each do |row|
+          row_text = row.map.with_index do |cell, index|
+            cell = format('%.6f', cell) if cell.is_a?(Float)
+            cell.to_s.ljust(column_widths[index])
+          end.join(' | ')
+
+          profiler_logger.info(row_text)
+        end
+
+        entries
+      end
+    end
+
+    module ClassMethods
+      # Simple fan-out logger that forwards to multiple underlying loggers
+      class MultiLogger
+        def initialize(*loggers)
+          @loggers = loggers.compact
+        end
+
+        def add(severity, message = nil, progname = nil)
+          @loggers.each { |logger| logger.add(severity, message, progname) }
+        end
+
+        def level=(level)
+          @loggers.each { |logger| logger.level = level }
+        end
+
+        def level
+          @loggers.map(&:level).min || Logger::INFO
+        end
+      end
+
+      def profiler_logger
+        @profiler_logger ||= begin
+          require 'logger'
+          logger = Logger.new($stdout)
+          logger.level = Logger::INFO
+          logger
+        end
+      end
+
+      def profiler_logger=(logger)
+        @profiler_logger = logger
+      end
+
+      # Configure logging to stdout
+      def enable_profiler_logging_to_stdout(level: Logger::INFO)
+        require 'logger'
+        self.profiler_logger = Logger.new($stdout).tap { |l| l.level = level }
+      end
+
+      # Configure logging to a file, optionally also to stdout
+      def enable_profiler_logging_to_file(path, level: Logger::INFO, shift_age: 0, shift_size: 1_048_576, also_stdout: false)
+        require 'logger'
+        file_logger = Logger.new(path, shift_age, shift_size)
+        file_logger.level = level
+        self.profiler_logger = if also_stdout
+                                 stdout_logger = Logger.new($stdout)
+                                 stdout_logger.level = level
+                                 MultiLogger.new(file_logger, stdout_logger)
+                               else
+                                 file_logger
+                               end
+      end
+    end
+  end
+end

data/lib/class_profiler/memory.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ClassProfiler
+  module Memory
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.extend(Methods::ClassMethods)
+      base.include(InstanceMethods)
+      base.include(ClassProfiler::Logging)
+    end
+
+    module InstanceMethods
+      # Stores per-method memory results
+      # { method_name => { allocated_objects: Integer, malloc_increase_bytes: Integer } }
+      def memory
+        @memory ||= {}
+      end
+
+      # Prints report of each method's allocated objects and bytes used
+      #
+      # @param include_zero [Boolean] include rows with zero deltas (default: true)
+      # @param sort_index [Integer] 0 for method, 1 for objects, 2 for bytes
+      # @return [Hash] memory entries
+      def memory_report(include_zero: true, sort_index: 0)
+        headers = %w[Method Objects Bytes]
+        entries = memory.map { |method, values| [method] + values.values }
+        print_report(entries, headers: headers, include_zero:, sort_index:)
+      end
+    end
+
+    module ClassMethods
+      # Unified API to select and track instance methods' memory
+      #
+      # @param inherited [Boolean] include inherited instance methods
+      # @param public [Boolean] include public methods
+      # @param protected [Boolean] include protected methods
+      # @param private [Boolean] include private methods
+      def track_memory(inherited: false, public: true, protected: true, private: true)
+        include_public = binding.local_variable_get(:public)
+        include_protected = binding.local_variable_get(:protected)
+        include_private = binding.local_variable_get(:private)
+
+        names = []
+        names |= select_instance_methods(visibility: :public, include_inherited: inherited) if include_public
+        names |= select_instance_methods(visibility: :protected, include_inherited: inherited) if include_protected
+        names |= select_instance_methods(visibility: :private, include_inherited: inherited) if include_private
+        measure_memory_for_methods(*names)
+      end
+      # (unified) Use track_memory to configure which methods are wrapped
+
+      # Wraps each method and records allocation deltas per call
+      #
+      # @param method_names [Array<Symbol>]
+      private def measure_memory_for_methods(*method_names)
+        require 'objspace'
+
+        method_names.each do |method_name|
+          wrap_method method_name do |original, *args, &block|
+            before_alloc_objects = GC.stat[:total_allocated_objects]
+            before_malloc_bytes = GC.stat[:malloc_increase_bytes] || 0
+
+            result = original.bind(self).call(*args, &block)
+
+            after_alloc_objects = GC.stat[:total_allocated_objects]
+            after_malloc_bytes = GC.stat[:malloc_increase_bytes] || 0
+
+            memory[method_name] = {
+              allocated_objects: after_alloc_objects - before_alloc_objects,
+              malloc_increase_bytes: after_malloc_bytes - before_malloc_bytes
+            }
+
+            result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/class_profiler/methods.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module ClassProfiler
+  module Methods
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(InstanceMethods)
+    end
+
+    module InstanceMethods; end
+
+    module ClassMethods
+      # Helper: exclude helper methods defined by ClassProfiler modules to avoid recursion/noise
+      def helper_owner_module?(owner)
+        owner_name = owner.respond_to?(:name) ? owner.name : nil
+        !!owner_name&.start_with?('ClassProfiler::')
+      end
+
+      # Methods that should never be wrapped on instances to avoid recursion/footguns
+      RESERVED_INSTANCE_METHODS = %i[
+        instance_exec instance_eval send __send__ method public_method
+        respond_to? object_id __id__ class inspect to_s
+      ].freeze
+
+      # Methods that should never be wrapped on the singleton to avoid recursion/footguns
+      RESERVED_SINGLETON_METHODS = %i[
+        send public_send method singleton_method define_singleton_method
+        instance_eval class_eval method_missing respond_to? allocate new superclass
+        inspect to_s name ancestors inherited extend include prepend
+        alias_method remove_method undef_method autoload autoload?
+        object_id __id__
+      ].freeze
+
+      # (internal) Helper: obtain singleton class
+      def singleton_class_of(klass)
+        class << klass; self; end
+      end
+
+      # Select instance method names by visibility and inheritance, excluding helpers/reserved
+      #
+      # @param visibility [Symbol] :public, :protected, :private, :all
+      # @param include_inherited [Boolean]
+      # @return [Array<Symbol>]
+      def select_instance_methods(visibility: :public, include_inherited: true)
+        names = case visibility
+                when :public      then public_instance_methods(include_inherited)
+                when :protected   then protected_instance_methods(include_inherited)
+                when :private     then private_instance_methods(include_inherited)
+                when :all         then (instance_methods(include_inherited) + protected_instance_methods(include_inherited) + private_instance_methods(include_inherited)).uniq
+                else public_instance_methods(include_inherited)
+                end
+
+        names.reject { |m| RESERVED_INSTANCE_METHODS.include?(m) || m.to_s.start_with?('_') || helper_owner_module?(instance_method(m).owner) }
+      end
+
+      # Select class method names by visibility and inheritance, excluding helpers/reserved
+      # @param visibility [Symbol] :public, :protected, :private, :all
+      # @param include_inherited [Boolean]
+      # @return [Array<Symbol>]
+      def select_class_methods(visibility: :public, include_inherited: true)
+        singleton = singleton_class_of(self)
+        inherit = include_inherited || false
+
+        names = case visibility
+                when :public      then singleton.public_instance_methods(inherit)
+                when :protected   then singleton.protected_instance_methods(inherit)
+                when :private     then singleton.private_instance_methods(inherit)
+                when :all         then (singleton.instance_methods(inherit) + singleton.protected_instance_methods(inherit) + singleton.private_instance_methods(inherit)).uniq
+                else singleton.public_instance_methods(inherit)
+                end
+
+        names.reject { |m| RESERVED_SINGLETON_METHODS.include?(m) || m.to_s.start_with?('_') || helper_owner_module?(singleton.instance_method(m).owner) }
+      end
+
+      # Wraps a method by creating an alias to the original method creating a new
+      # method in its place, executing the passed in block and returning the result
+      # The given block is executed in the INSTANCE context via instance_exec.
+      #
+      # @yield [original_method, *args] wrapper executed in instance context
+      def wrap_method(method_name, *_args, prefix: '_', &wrapper)
+        wrapped_method_name = "#{prefix}#{method_name}".to_sym
+        alias_method wrapped_method_name, method_name
+        wrapped_method = instance_method(wrapped_method_name)
+
+        define_method(method_name) do |*args|
+          instance_exec(wrapped_method, *args, &wrapper)
+        end
+      end
+
+      # Wrap a class method on the singleton class
+      def wrap_class_method(method_name, *_args, prefix: '_', &wrapper)
+        singleton = singleton_class_of(self)
+        wrapped_method_name = "#{prefix}#{method_name}".to_sym
+        singleton.alias_method wrapped_method_name, method_name
+        singleton.define_method(method_name) do |*args, &block|
+          start_time = Time.now
+          result = send(wrapped_method_name, *args, &block)
+          # let wrapper decide what to record/return
+          # wrapper executed in singleton context
+          wrapper.call(start_time, result, method_name)
+        end
+      end
+    end
+  end
+end

data/lib/class_profiler/performance.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module ClassProfiler
+  module Performance
+    def self.included(base)
+      base.extend(ClassMethods)
+      # Ensure the including class has access to wrap_method
+      base.extend(Methods::ClassMethods)
+      base.include(InstanceMethods)
+    end
+
+    module InstanceMethods
+      def performance
+        @performance ||= {}
+      end
+
+      # Prints all performance-measured instance methods and the time taken per method (seconds)
+      #
+      # @param include_zero [Boolean] include methods with 0.0s measurements
+      # @param sort_index [Integer] 0 for method, 1 for time, 2 for total
+      #
+      # @return [Hash]
+      def performance_report(include_zero: false, sort_index: 1)
+        headers = %w[Method Time Total]
+        entries = performance.map do |method, values|
+          if values.is_a?(Hash)
+            [method, values[:time], values[:total]]
+          else
+            [method, values, values]
+          end
+        end
+        print_report(entries, headers: headers, include_zero: include_zero, sort_index: sort_index)
+      end
+    end
+
+    module ClassMethods
+      include Methods::ClassMethods
+
+      # Unified API to select and track instance methods' performance
+      #
+      # @param inherited [Boolean] include inherited instance methods
+      # @param public [Boolean] include public methods
+      # @param protected [Boolean] include protected methods
+      # @param private [Boolean] include private methods
+      def track_performance(inherited: false, public: true, protected: true, private: true)
+        include_public = binding.local_variable_get(:public)
+        include_protected = binding.local_variable_get(:protected)
+        include_private = binding.local_variable_get(:private)
+
+        names = []
+        names |= select_instance_methods(visibility: :public, include_inherited: inherited) if include_public
+        names |= select_instance_methods(visibility: :protected, include_inherited: inherited) if include_protected
+        names |= select_instance_methods(visibility: :private, include_inherited: inherited) if include_private
+        measure_performance_for_methods(*names)
+      end
+
+      # Measures non-inherited instance methods
+      #
+      # @param visibility [Symbol] :public, :protected, :private, :all
+      def performance_instance_methods(visibility: :public)
+        names = select_instance_methods(visibility: visibility, include_inherited: false)
+        performance_methods(*names)
+      end
+
+      # Records how long each method call takes and saves it to `performance` hash
+      #
+      # @param method_names [Array<Symbol>] the names of the methods to measure
+      private def measure_performance_for_methods(*method_names)
+        method_names.each do |method_name|
+          wrap_method method_name do |original, *args, &block|
+            start_time = Time.now
+            result = original.bind(self).call(*args, &block)
+            end_time = Time.now
+            duration = end_time - start_time
+            performance[method_name] ||= { total: 0 }
+            performance[method_name][:total] += duration
+            performance[method_name][:time] = duration
+            result
+          end
+        end
+      end
+    end
+  end
+end

data/lib/class_profiler.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'class_profiler/methods'
+require_relative 'class_profiler/performance'
+require_relative 'class_profiler/logging'
+require_relative 'class_profiler/memory'
+
+module ClassProfiler
+  NAME = 'class-profiler'
+  VERSION = '0.1.0'
+
+  def self.included(base)
+    base.include(ClassProfiler::Performance)
+    base.include(ClassProfiler::Memory)
+    base.include(ClassProfiler::Logging)
+    base.include(InstanceMethods)
+  end
+
+  module InstanceMethods
+    def profile
+      perf = performance.transform_values do |value|
+        if value.is_a?(Hash)
+          { time: value[:time] }
+        else
+          { time: value }
+        end
+      end
+      mem = memory.transform_values { |values| { objects: values[:allocated_objects], bytes: values[:malloc_increase_bytes] } }
+      perf.merge(mem) { |_k, a, b| a.merge(b) }
+    end
+
+    def profile_report(include_zero: true, sort_index: 0)
+      headers = %w[Method Time Objects Bytes]
+      entries = profile.map { |method, values| [method, values[:time], values[:objects], values[:bytes]] }
+      print_report(entries, headers: headers, include_zero:, sort_index:)
+    end
+  end
+end

data/rakefile.rb

@@ -0,0 +1,27 @@
+# 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]
+
+desc 'Run all available examples'
+task :examples do
+  examples_dir = File.expand_path('examples', __dir__)
+  scripts = Dir[File.join(examples_dir, '*.rb')].sort
+  if scripts.empty?
+    puts 'No scripts found in examples/'
+    next
+  end
+
+  scripts.each do |script|
+    puts "\n\n=== Running: #{File.basename(script)} ==="
+    system({ 'BUNDLE_GEMFILE' => File.expand_path('Gemfile', __dir__) }, RbConfig.ruby, script)
+  end
+end

metadata

@@ -0,0 +1,188 @@
+--- !ruby/object:Gem::Specification
+name: class-profiler
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Greenfield
+bindir: bin
+cert_chain: []
+date: 2025-09-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-stack_explorer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: "\n    Quickly benchmark execution time and profile memory allocations
+  for specific\n    or all instance methods within a class. Include ClassProfiler
+  to get\n    `benchmark_methods` and `profile_methods` helpers and collect results
+  via\n    `benchmarked` and `profiled_memory`.\n  "
+email:
+- mattgreenfield1@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/main.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- Gemfile
+- Gemfile.lock
+- Guardfile
+- LICENSE.txt
+- README.md
+- bin/console
+- bin/setup
+- class-profiler.gemspec
+- config.yml
+- lib/class_profiler.rb
+- lib/class_profiler/logging.rb
+- lib/class_profiler/memory.rb
+- lib/class_profiler/methods.rb
+- lib/class_profiler/performance.rb
+- rakefile.rb
+homepage: https://github.com/omgreenfield/class-profiler
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Benchmark speed and profile memory of class methods
+test_files: []