rails_tracepoint_stack 0.3.5 → 0.5.0

data/lib/rails_tracepoint_stack/tracer.rb

@@ -3,30 +3,123 @@ require "rails_tracepoint_stack/logger"
 require "rails_tracepoint_stack/trace_filter"
 require "rails_tracepoint_stack/trace"
 require "rails_tracepoint_stack/log_formatter"
+require "rails_tracepoint_stack/sink/log"
+require "rails_tracepoint_stack/depth_tracker"
 
 module RailsTracepointStack
   class Tracer
     include RailsTracepointStack::TraceFilter
     extend Forwardable
- 
+
+    DEFAULT_EVENTS = [:call].freeze
+
     def_delegators :@tracer, :enable, :disable
 
-    def initialize
+    # How many traces the filters dropped. A capture that keeps nothing is
+    # ambiguous on its own: this tells the difference between code that never
+    # ran and code that ran entirely inside gems.
+    attr_reader :filtered_count
+
+    # A nil thread watches every thread in the process, which is what the
+    # global tracer wants. Passing one confines tracing to it, so a capture
+    # running inside a threaded server does not pick up other requests.
+    # own_block is the block the caller wrapped around the code under
+    # inspection. It is the caller's own code, so it is skipped before a depth
+    # is assigned - otherwise it would indent the whole trace by a level it
+    # never shows.
+    def initialize(
+      sink: RailsTracepointStack::Sink::Log.new,
+      events: DEFAULT_EVENTS,
+      thread: nil,
+      own_block: nil
+    )
+      @sink = sink
+      @events = events
+      @thread = thread
+      # Ruby has grown extra entries on source_location over time (columns, end
+      # positions), so only the file and the line are compared.
+      @own_block_location = own_block&.source_location&.first(2)
+      @filtered_count = 0
       generate_tracer
     end
 
     private
 
     def generate_tracer
-      @tracer ||= TracePoint.new(:call) do |tracepoint|
+      @tracer ||= TracePoint.new(*@events) do |tracepoint|
+        next if out_of_scope_thread?
+
         trace = RailsTracepointStack::Trace.new(trace_point: tracepoint)
 
-        next if ignore_trace?(trace: trace)
+        next if own_block?(trace)
+
+        if ignore_trace?(trace: trace)
+          @filtered_count += 1
+          next
+        end
+
+        trace.depth = depth_for(trace)
+        @sink.record(trace)
+      end
+    end
+
+    # Matching on location alone would also drop a block written on the same
+    # line as the capture call. The caller's block is the first to arrive from
+    # that location, so only that one is skipped, along with its return.
+    def own_block?(trace)
+      return false if @own_block_location.nil?
 
-        # TODO: Use proper OO
-        message = RailsTracepointStack::LogFormatter.message trace
-        RailsTracepointStack::Logger.log message
+      case trace.kind
+      when :b_call then claim_own_block(trace)
+      when :b_return then release_own_block(trace)
+      else false
       end
     end
+
+    def claim_own_block(trace)
+      return false if @own_block_seen
+      return false unless [trace.file_path, trace.line_number] == @own_block_location
+
+      @own_block_seen = true
+      @own_block_position = raw_stack_position
+      true
+    end
+
+    def release_own_block(trace)
+      return false unless @own_block_position && raw_stack_position == @own_block_position
+
+      @own_block_position = nil
+      true
+    end
+
+    def out_of_scope_thread?
+      !@thread.nil? && Thread.current != @thread
+    end
+
+    # Only kept traces pay for reading the stack position, so the cost stays
+    # proportional to the app code being traced rather than to everything the
+    # VM runs underneath it.
+    def depth_for(trace)
+      tracker = depth_tracker
+      raw_position = raw_stack_position
+
+      case trace.kind
+      when :call, :b_call then tracker.enter(raw_position)
+      when :return, :b_return then tracker.leave(raw_position)
+      when :raise then tracker.raised(raw_position)
+      end
+    end
+
+    def raw_stack_position
+      caller_locations(1)&.length || 0
+    end
+
+    def depth_tracker
+      Thread.current[depth_tracker_key] ||= RailsTracepointStack::DepthTracker.new
+    end
+
+    def depth_tracker_key
+      @depth_tracker_key ||= :"rails_tracepoint_stack_depth_#{object_id}"
+    end
   end
 end

data/lib/rails_tracepoint_stack/truncator.rb

@@ -0,0 +1,85 @@
+require "json"
+
+module RailsTracepointStack
+  # Shrinks an already-serialized value so one fat argument (a big payload, a
+  # long SQL string, a loaded association) cannot dominate the output. Runs
+  # over the plain structures LogFormatter.safe_value produces, so it only
+  # ever sees strings, numbers, booleans, nil, arrays and hashes.
+  module Truncator
+    ELLIPSIS = "…".freeze
+
+    # Per-string and per-collection limits still leave room for one value to
+    # run to thousands of characters: twenty items each truncated to two
+    # hundred is still four thousand. This caps the value as a whole, and does
+    # it before the per-item truncation so the summary can report the real
+    # size rather than the already-shrunk one.
+    def self.bounded(value, limits)
+      capped = cap(value, limits)
+      return capped unless capped.equal?(value)
+
+      call(value, limits)
+    end
+
+    def self.cap(value, limits)
+      max = limits.max_value_length
+      return value if max.nil?
+      return value unless value.is_a?(String) || value.is_a?(Array) || value.is_a?(Hash)
+
+      size = JSON.generate(value).length
+      return value if size <= max
+
+      summarize(value, size)
+    rescue SystemStackError, StandardError
+      value
+    end
+
+    def self.summarize(value, size)
+      case value
+      when Array then "[#{value.size} items, #{size} chars — over max_value_length]"
+      when Hash then "{#{value.size} keys, #{size} chars — over max_value_length}"
+      else "[#{size} chars — over max_value_length]"
+      end
+    end
+
+    def self.call(value, limits)
+      case value
+      when String then truncate_string(value, limits)
+      when Array then truncate_array(value, limits)
+      when Hash then truncate_hash(value, limits)
+      else value
+      end
+    end
+
+    def self.truncate_string(value, limits)
+      max = limits.max_string_length
+      return value if max.nil? || value.length <= max
+
+      "#{value[0, max]}#{ELLIPSIS} (#{value.length} chars)"
+    end
+
+    def self.truncate_array(value, limits)
+      max = limits.max_collection_size
+      kept = (max.nil? || value.length <= max) ? value : value.first(max)
+      result = kept.map { |item| call(item, limits) }
+
+      return result if kept.length == value.length
+
+      result << "(+#{value.length - kept.length} more)"
+    end
+
+    def self.truncate_hash(value, limits)
+      max = limits.max_collection_size
+      dropped = (max.nil? || value.size <= max) ? 0 : value.size - max
+      kept = dropped.zero? ? value : value.first(max).to_h
+
+      result = kept.each_with_object({}) do |(key, item), memo|
+        memo[key] = call(item, limits)
+      end
+
+      return result if dropped.zero?
+
+      result[ELLIPSIS] = "(+#{dropped} more)"
+      result
+    end
+  end
+end

data/lib/rails_tracepoint_stack/version.rb

@@ -1,3 +1,3 @@
 module RailsTracepointStack
-  VERSION = "0.3.5"
+  VERSION = "0.5.0"
 end

data/lib/rails_tracepoint_stack.rb

@@ -1,6 +1,10 @@
 require 'rails_tracepoint_stack/configuration'
 require 'rails_tracepoint_stack/log_formatter'
 require 'rails_tracepoint_stack/tracer'
+require 'rails_tracepoint_stack/limits'
+require 'rails_tracepoint_stack/skill_installer'
+require 'rails_tracepoint_stack/sink/collector'
+require 'rails_tracepoint_stack/trace_session'
 
 $rails_tracer_rtps = nil
 
@@ -17,6 +21,43 @@ module RailsTracepointStack
     yield(configuration)
   end
 
+  CAPTURE_EVENTS = [:call, :return, :raise].freeze
+  BLOCK_EVENTS = [:b_call, :b_return].freeze
+
+  # Traces a block and hands back everything that happened inside it, instead
+  # of writing to a log. Meant to be run as a one-off: capture, read, done.
+  # Blocks are off by default: a block written inside a loop fires once per
+  # element, so watching them costs more traces than watching methods does.
+  # Turn them on to see scopes, lambdas and anything else whose logic lives in
+  # a block rather than a method.
+  def self.capture(threads: :current, blocks: false, **limit_options, &traced)
+    raise ArgumentError, "Block not given to #capture" unless traced
+
+    collector = RailsTracepointStack::Sink::Collector.new(
+      limits: RailsTracepointStack::Limits.new(**limit_options)
+    )
+    session = collector.session
+    tracer = RailsTracepointStack::Tracer.new(
+      sink: collector,
+      events: blocks ? CAPTURE_EVENTS + BLOCK_EVENTS : CAPTURE_EVENTS,
+      thread: (threads == :all) ? nil : Thread.current,
+      own_block: traced
+    )
+
+    tracer.enable
+    begin
+      session.result = traced.call(session)
+    rescue Exception => error
+      session.error = error
+      raise
+    ensure
+      tracer.disable
+      session.filtered_count = tracer.filtered_count
+    end
+
+    session
+  end
+
   def self.enable_trace
     raise ArgumentError, "Block not given to #enable_trace" unless block_given?
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_tracepoint_stack
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.5.0
 platform: ruby
 authors:
 - Carlos Daniel Pohlod
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-17 00:00:00.000000000 Z
+date: 2026-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -70,33 +70,50 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.39.1
-description: A formatted output of all methods called in your rails application of
-  code created by the developer, with the complete path to the class/module, including
-  passed params.
+description: Traces a block of your Rails app and returns the call tree of your own
+  code - arguments, return values, raised exceptions and call depth - with gems, the
+  framework and stdlib filtered out. Bounded output meant to be read directly, by
+  a developer or by an AI coding agent debugging the app.
 email: carlospohlod@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
+- changelog.md
+- lib/generators/rails_tracepoint_stack/install/install_generator.rb
 - lib/rails_tracepoint_stack.rb
 - lib/rails_tracepoint_stack/configuration.rb
+- lib/rails_tracepoint_stack/depth_tracker.rb
 - lib/rails_tracepoint_stack/filter/custom_trace_selector_filter.rb
 - lib/rails_tracepoint_stack/filter/gem_path.rb
 - lib/rails_tracepoint_stack/filter/rb_config.rb
 - lib/rails_tracepoint_stack/filter/trace_from_dependencies_filter.rb
 - lib/rails_tracepoint_stack/filter/trace_from_ruby_code_filter.rb
 - lib/rails_tracepoint_stack/filter/trace_to_ignore_filter.rb
+- lib/rails_tracepoint_stack/limits.rb
 - lib/rails_tracepoint_stack/log_formatter.rb
 - lib/rails_tracepoint_stack/logger.rb
+- lib/rails_tracepoint_stack/renderer/summary.rb
+- lib/rails_tracepoint_stack/renderer/tree.rb
+- lib/rails_tracepoint_stack/sink/collector.rb
+- lib/rails_tracepoint_stack/sink/log.rb
+- lib/rails_tracepoint_stack/skill_installer.rb
+- lib/rails_tracepoint_stack/templates/skill.md
 - lib/rails_tracepoint_stack/trace.rb
 - lib/rails_tracepoint_stack/trace_filter.rb
+- lib/rails_tracepoint_stack/trace_record.rb
+- lib/rails_tracepoint_stack/trace_session.rb
 - lib/rails_tracepoint_stack/tracer.rb
+- lib/rails_tracepoint_stack/truncator.rb
 - lib/rails_tracepoint_stack/version.rb
-homepage: https://github.com/carlosdanielpohlod/rails_tracepoint_stack/
+homepage: https://carlosdanielpohlod.github.io/rails_tracepoint_stack/
 licenses:
 - MIT
 metadata:
-  documentation_uri: https://github.com/carlosdanielpohlod/rails_tracepoint_stack/
+  source_code_uri: https://github.com/carlosdanielpohlod/rails_tracepoint_stack
+  documentation_uri: https://github.com/carlosdanielpohlod/rails_tracepoint_stack#readme
+  bug_tracker_uri: https://github.com/carlosdanielpohlod/rails_tracepoint_stack/issues
   changelog_uri: https://github.com/carlosdanielpohlod/rails_tracepoint_stack/blob/main/changelog.md
 post_install_message:
 rdoc_options: []
@@ -116,5 +133,6 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: Get a complete stack trace for your code on a Rails application.
+summary: 'Runtime call tree for a Rails app: which methods ran, with what params,
+  and what they returned.'
 test_files: []