ruby_method_tracer 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 673fbc66c79fb1b2466d43fad6be1f738a8978630073283cda616b179beb8c8d
+  data.tar.gz: 92d557e3061f52f950747fd6a314c22facbd89ff3be790c223f71316ca50a69f
+SHA512:
+  metadata.gz: cba38cde9f2ddf19a523abb9b1409832620ad9568b43dfb131bf0243119052134ec7b21e097fa8568d04801d32bf3918747844d87bbff54a4e06a39be3fecc74
+  data.tar.gz: c2f90be756be60ce89ba83348a38feb797922923bbe5434c2f421a492c890f3d51b8eff32b53506958fb554baafed58d7e15758803bbead740ef53b759390c0f

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,27 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
+  NewCops: enable
+  Exclude:
+    - 'examples/**/*'
+    - 'vendor/**/*'
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Metrics/MethodLength:
+  Max: 15
+Metrics/ClassLength:
+  Max: 120
+
+RSpec/MultipleExpectations:
+  Max: 15
+
+RSpec/ExampleLength:
+  Max: 15

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-09-03
+## [0.1.0] - 2025-09-16
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Seun Adekunle
+
+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,109 @@
+[![Ruby](https://github.com/Seunadex/ruby_method_tracer/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/Seunadex/ruby_method_tracer/actions/workflows/main.yml)
+
+# RubyMethodTracer
+
+RubyMethodTracer is a lightweight Ruby mixin for targeted method tracing. It wraps instance methods, measures wall-clock runtime, flags errors, and can stream results to your logger without pulling in a full APM agent. Use it to surface slow paths in production or gather quick instrumentation while debugging.
+
+## Highlights
+- Wrap only the methods you care about; public, protected, and private methods are supported.
+- Records duration, success/error state, and timestamps with thread-safe storage.
+- Configurable threshold to ignore fast calls and optional log streaming via `Logger`.
+- Zero dependencies beyond the Ruby standard library, keeping overhead minimal.
+
+## Installation
+
+This project has not yet been published to RubyGems.
+
+Add it to your Gemfile directly from GitHub:
+
+```ruby
+# Gemfile
+gem "ruby_method_tracer", github: "Seunadex/ruby_method_tracer"
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+For local development or experimentation:
+
+```bash
+git clone https://github.com/Seunadex/ruby_method_tracer.git
+cd method_tracer
+bundle exec rake install
+```
+
+## Usage
+
+Include `RubyMethodTracer` in any class whose instance methods you want to observe. Register the target methods with optional settings.
+
+```ruby
+require "ruby_method_tracer"
+
+class Worker
+  include RubyMethodTracer
+
+  def perform(user_id)
+    expensive_call(user_id)
+  end
+
+  private
+
+  def expensive_call(id)
+    # work...
+  end
+end
+
+Worker.trace_methods(:perform, threshold: 0.005, auto_output: true)
+
+Worker.new.perform(42)
+```
+
+With `auto_output: true`, each invocation prints a colorized summary:
+
+```
+TRACE: Worker#perform [OK] took 6.3ms
+```
+
+To inspect trace results programmatically, manage the tracer yourself:
+
+```ruby
+tracer = RubyMethodTracer::SimpleTracer.new(Worker, threshold: 0.002)
+tracer.trace_method(:perform)
+
+Worker.new.perform(42)
+
+pp tracer.fetch_results
+# => {
+#      total_calls: 1,
+#      total_time: 0.0063,
+#      calls: [
+#        { method_name: "Worker#perform", execution_time: 0.0063, status: :success, ... }
+#      ]
+#    }
+```
+
+### Options
+
+- `threshold` (Float, default `0.001`): minimum duration (in seconds) to record.
+- `auto_output` (Boolean, default `false`): emit a log line using `Logger` for each recorded call.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run `rake spec` to execute the test suite. You can also run `bin/console` for an interactive prompt.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version in `lib/ruby_method_tracer/version.rb`, and then run `bundle exec rake release`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Seunadex/ruby_method_tracer. 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/Seunadex/ruby_method_tracer/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). See `LICENSE.txt` for details.
+
+## Code of Conduct
+
+Everyone interacting in the RubyMethodTracer project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/Seunadex/ruby_method_tracer/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/ruby_method_tracer/simple_tracer.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "set"
+require "logger"
+
+module RubyMethodTracer
+  # SimpleTracer wraps instance methods on a target class and records
+  # execution metrics for each invocation. It measures wall-clock duration,
+  # captures success or error status, stores results in-memory, and can
+  # optionally print each trace as it happens.
+  #
+  # Options:
+  # - :threshold (Float): Minimum duration in seconds to record; defaults to 0.001 (1ms).
+  # - :auto_output (Boolean): When true, prints each call summary; defaults to false.
+  #
+  # Usage:
+  #   tracer = RubyMethodTracer::SimpleTracer.new(MyClass, threshold: 0.005)
+  #   tracer.trace_method(:expensive_call)
+  #   results = tracer.fetch_results
+  class SimpleTracer # rubocop:disable Metrics/ClassLength
+    def initialize(target_class, **options)
+      @target_class = target_class
+      @options = default_options.merge(options)
+      @calls = []
+      @lock  = Mutex.new # Mutex to make writes to @calls thread safe.
+      @wrapped_methods = Set.new
+      @logger = Logger.new($stdout)
+    end
+
+    def trace_method(name)
+      method_name = name.to_sym
+      visibility = method_visibility(method_name)
+      return unless visibility
+      return unless mark_wrapped?(method_name)
+
+      aliased = alias_for(method_name)
+      @target_class.send(:alias_method, aliased, method_name) # Aliases original implementation to our private name.
+
+      tracer = self
+      key = :__ruby_method_tracer_in_trace # local key to avoid recursive tracing.
+
+      # Defines a new method with the original name that delegates to our wrapper.
+      @target_class.define_method(method_name, &build_wrapper(aliased, method_name, key, tracer))
+
+      @target_class.send(visibility, method_name) # Restores the original visibility after redefine.
+    end
+
+    def record_call(method_name, execution_time, status, error = nil)
+      return if execution_time < @options[:threshold]
+
+      call_details = {
+        method_name: "#{@target_class}##{method_name}",
+        execution_time: execution_time,
+        status: status,
+        error: error,
+        timestamp: Time.now
+      }
+
+      @lock.synchronize { @calls << call_details } # Thread safe append to shared results arrray.
+
+      output_call(call_details) if @options[:auto_output]
+    end
+
+    def fetch_results
+      snapshot = nil
+      @lock.synchronize { snapshot = @calls.dup } # Copies under lock to prevent races while reading.
+
+      {
+        total_calls: snapshot.size,
+        total_time: snapshot.sum { |call| call[:execution_time] },
+        calls: snapshot
+      }
+    end
+
+    private
+
+    def default_options
+      {
+        threshold: 0.001,
+        auto_output: false
+      }
+    end
+
+    def method_visibility(method_name)
+      return :private if @target_class.private_method_defined?(method_name)
+      return :protected if @target_class.protected_method_defined?(method_name)
+      return :public if @target_class.method_defined?(method_name)
+
+      nil
+    end
+
+    # Marks a method as wrapped to avoid duplicates
+    def mark_wrapped?(method_name)
+      return false if @wrapped_methods.include?(method_name)
+
+      @wrapped_methods << method_name
+      true
+    end
+
+    def alias_for(method_name)
+      :"__ruby_method_tracer_original_#{method_name}__"
+    end
+
+    def build_wrapper(aliased, method_name, key, tracer)
+      proc do |*args, **kwargs, &block|                                # Captures args and block exactly like original.
+        tracer.__send__(:wrap_call, method_name, key) do               # Delegates to wrapper to handle timing and flag.
+          __send__(aliased, *args, **kwargs, &block)                   # Calls the original aliased implementation.
+        end
+      end
+    end
+
+    def wrap_call(method_name, key)
+      return yield if Thread.current[key]
+
+      Thread.current[key] = true
+      start = monotonic_time
+      begin
+        result = yield
+        record_call(method_name, monotonic_time - start, :success)
+        result
+      rescue StandardError => e
+        record_call(method_name, monotonic_time - start, :error, e)
+        raise
+      ensure
+        Thread.current[key] = false
+      end
+    end
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def output_call(call)
+      time_str = colorize(format_time(call[:execution_time]), :yellow)
+      status_str = call[:status] == :error ? colorize("[ERROR]", :red) : colorize("[OK]", :green)
+      method_name = colorize(call[:method_name], :cyan)
+      if call[:status] == :error
+        @logger.warn(
+          "TRACE: #{method_name} #{status_str} took #{time_str} - Error: #{call[:error].class}: #{call[:error].message}"
+        )
+      else
+        @logger.info("TRACE: #{method_name} #{status_str} took #{time_str}")
+      end
+    end
+
+    def format_time(seconds)
+      if seconds >= 1.0
+        "#{seconds.round(3)}s"
+      elsif seconds >= 0.001
+        "#{(seconds * 1000).round(1)}ms"
+      else
+        "#{(seconds * 1_000_000).round(0)}µs"
+      end
+    end
+
+    def colorize(text, color)
+      colors = {
+        red: "31",
+        green: "32",
+        yellow: "33",
+        blue: "34",
+        magenta: "35",
+        cyan: "36",
+        white: "37",
+        reset: "0"
+      }
+      "\e[#{colors[color]}m#{text}\e[#{colors[:reset]}m"
+    end
+  end
+end

data/lib/ruby_method_tracer/version.rb

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

data/lib/ruby_method_tracer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "ruby_method_tracer/version"
+require_relative "ruby_method_tracer/simple_tracer"
+
+# Public: Mixin that adds lightweight method tracing to classes.
+#
+# When included, this module extends the host class with a class-level
+# API (`trace_methods`) that wraps selected instance methods using
+# `RubyMethodTracer::SimpleTracer`. Wrapped methods record execution timing and
+# errors with minimal overhead, suitable for ad-hoc performance debugging
+# in development or selective tracing in production.
+#
+# Example
+#   class Worker
+#     include RubyMethodTracer
+#     def perform; do_work; end
+#   end
+#   Worker.trace_methods(:perform, threshold: 0.005, auto_output: true)
+#
+# See `RubyMethodTracer::SimpleTracer` for available options.
+module RubyMethodTracer
+  class Error < StandardError; end
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  # Class-level API mixed into including classes.
+  #
+  # Provides `trace_methods`, which wraps the specified instance methods on the
+  # target class using `RubyMethodTracer::SimpleTracer`. Each wrapped method records
+  # execution metrics (duration, status, errors) with minimal intrusion.
+  #
+  # Usage:
+  #   class MyService
+  #     include RubyMethodTracer
+  #     def call; expensive_work; end
+  #   end
+  #   MyService.trace_methods(:call, threshold: 0.005, auto_output: true)
+  module ClassMethods
+    def trace_methods(*method_names, **options)
+      tracer = SimpleTracer.new(self, **options)
+      method_names.each do |method_name|
+        tracer.trace_method(method_name)
+      end
+    end
+  end
+end

data/sig/ruby_method_tracer.rbs

@@ -0,0 +1,4 @@
+module RubyMethodTracer
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: ruby_method_tracer
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Seun Adekunle
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-10-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+description: A developer-friendly gem for tracing method calls, execution times, with
+  minimal overhead.
+email:
+- adekunleseun001@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ruby_method_tracer.rb
+- lib/ruby_method_tracer/simple_tracer.rb
+- lib/ruby_method_tracer/version.rb
+- sig/ruby_method_tracer.rbs
+homepage: https://github.com/seunadex/ruby_method_tracer
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/Seunadex/ruby_method_tracer/blob/main/README.md
+  source_code_uri: https://github.com/seunadex/ruby_method_tracer
+  changelog_uri: https://github.com/seunadex/ruby_method_tracer/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Lightweight method tracing for Ruby applications
+test_files: []