rails_tracepoint_stack 0.3.5 → 0.5.0

data/lib/rails_tracepoint_stack/renderer/tree.rb

@@ -0,0 +1,142 @@
+require "json"
+
+module RailsTracepointStack
+  module Renderer
+    # Renders a session as an indented call tree.
+    #
+    # The format is built for reading in a terminal or pasting into a prompt,
+    # so it favours short lines: paths are relative to the working directory,
+    # values are compact JSON, and a return sits one level under the call it
+    # belongs to.
+    module Tree
+      INDENT = "  ".freeze
+
+      def self.call(session)
+        lines = session.traces.map { |record| line_for(record) }
+        lines << truncation_notice if session.truncated?
+        lines << Summary.line(session)
+        lines << empty_notice(session) if session.traces.empty?
+        lines.join("\n")
+      end
+
+      # An empty tree reads like a broken tool. It usually means the block ran
+      # entirely inside gems - a bare ActiveRecord query calls no method the
+      # developer wrote - so say which of the two happened.
+      def self.empty_notice(session)
+        return "no code ran inside the block" if session.filtered_count.to_i.zero?
+
+        "no app code ran: #{session.filtered_count} traces from gems, the framework " \
+          "and Ruby itself were filtered out"
+      end
+
+      def self.line_for(record)
+        case record.kind
+        when :call then call_line(record)
+        when :b_call then block_line(record)
+        when :return, :b_return then return_line(record)
+        when :raise then raise_line(record)
+        end
+      end
+
+      # A block has no name of its own. TracePoint reports the method it was
+      # written in, which is the useful label; a block written at class-body
+      # level - a scope, a lambda constant - has neither, so the location is
+      # all there is to show.
+      def self.block_line(record)
+        "#{indent(record.depth)}#{repeat_marker(record)}#{block_name(record)} { } " \
+          "(#{location(record)}) #{compact(record.params)}"
+      end
+
+      def self.block_name(record)
+        return "block" if record.class_name.nil? || record.method_name.nil?
+
+        qualified_name(record)
+      end
+
+      def self.repeat_marker(record)
+        count = record.repeats.to_i
+        return "" if count <= 1
+
+        "↻ #{count}× "
+      end
+
+      # Stops at the first character that cannot be part of a constant name, so
+      # a singleton class that printed extra detail after its name still
+      # resolves. Requires a leading capital, which keeps anonymous singletons
+      # like #<Class:0x00007f1234> out.
+      SINGLETON_CLASS = /\A#<Class:([A-Z][\w:]*)[\s(>]/
+      TEMPLATE_FILE = /\.(erb|haml|slim|builder|jbuilder|rabl)\z/i
+      # Everything a template receives besides the locals belongs to the
+      # rendering machinery, not to the developer.
+      TEMPLATE_LOCALS = "local_assigns".freeze
+
+      def self.call_line(record)
+        return template_line(record) if template?(record)
+
+        "#{indent(record.depth)}#{qualified_name(record)} " \
+          "(#{location(record)}) #{compact(record.params)}"
+      end
+
+      # A class method is defined on the singleton class, which prints as
+      # #<Class:Foo>. Ruby writes that call as Foo.bar, so the tree does too.
+      # An anonymous singleton prints as an address and is left alone, since
+      # turning that into `0x00007f1234.render` helps nobody.
+      def self.qualified_name(record)
+        singleton = SINGLETON_CLASS.match(record.class_name.to_s)
+        return "#{singleton[1]}.#{record.method_name}" if singleton
+
+        "#{record.class_name}##{record.method_name}"
+      end
+
+      # A compiled template is a generated method on an anonymous class, named
+      # after a hash of the file. None of that is worth showing: the path is.
+      def self.template?(record)
+        TEMPLATE_FILE.match?(record.file_path.to_s)
+      end
+
+      def self.template_line(record)
+        "#{indent(record.depth)}render #{relative_path(record.file_path)} " \
+          "#{compact(template_locals(record))}"
+      end
+
+      def self.template_locals(record)
+        params = record.params
+        return {} unless params.is_a?(Hash)
+
+        params.fetch(TEMPLATE_LOCALS, {})
+      end
+
+      def self.return_line(record)
+        "#{indent(record.depth + 1)}-> #{compact(record.return_value)}"
+      end
+
+      def self.raise_line(record)
+        "#{indent(record.depth + 1)}!! #{record.exception_class}: #{record.exception_message}"
+      end
+
+      def self.truncation_notice
+        "... truncated: the limit was reached before the block finished"
+      end
+
+      def self.indent(depth)
+        INDENT * depth
+      end
+
+      def self.location(record)
+        "#{relative_path(record.file_path)}:#{record.line_number}"
+      end
+
+      def self.relative_path(file_path)
+        return file_path unless file_path.to_s.start_with?("#{Dir.pwd}/")
+
+        file_path[(Dir.pwd.length + 1)..]
+      end
+
+      def self.compact(value)
+        JSON.generate(value)
+      rescue SystemStackError, StandardError
+        value.to_s
+      end
+    end
+  end
+end

data/lib/rails_tracepoint_stack/sink/collector.rb

@@ -0,0 +1,138 @@
+require "rails_tracepoint_stack/limits"
+require "rails_tracepoint_stack/log_formatter"
+require "rails_tracepoint_stack/trace_record"
+require "rails_tracepoint_stack/trace_session"
+require "rails_tracepoint_stack/truncator"
+
+module RailsTracepointStack
+  module Sink
+    # Turns live traces into immutable records held in memory, so a caller can
+    # inspect them once the traced block is done.
+    class Collector
+      attr_reader :session, :limits
+
+      def initialize(session: RailsTracepointStack::TraceSession.new, limits: RailsTracepointStack::Limits.new)
+        @session = session
+        @limits = limits
+        @open_block = nil
+        @suppressed_returns = Hash.new(0)
+      end
+
+      def record(trace)
+        return if limits.too_deep?(trace.depth)
+
+        unless limits.room_for?(session.traces.size)
+          session.truncated = true
+          return
+        end
+
+        built = build_record(trace)
+        return if collapsed?(built)
+
+        session.add(built)
+      end
+
+      private
+
+      # A block written inside a loop runs once per element and reports the
+      # same location every time, which buries the trace it belongs to. Runs of
+      # the same block at the same depth become one record carrying a count,
+      # and the matching returns are dropped with them.
+      def collapsed?(record)
+        return drop_suppressed_return(record) if record.block_return?
+        return break_run(record) unless record.block_call?
+
+        key = [record.file_path, record.line_number, record.depth]
+
+        if @open_block && @open_block.first == key
+          @open_block.last.repeats += 1
+          @suppressed_returns[record.depth] += 1
+          return true
+        end
+
+        @open_block = [key, record]
+        false
+      end
+
+      def drop_suppressed_return(record)
+        return false unless @suppressed_returns[record.depth] > 0
+
+        @suppressed_returns[record.depth] -= 1
+        true
+      end
+
+      # Anything that is not part of the block's own call/return pair ends the
+      # run, so two separate loops over the same line stay separate.
+      def break_run(record)
+        @open_block = nil unless record.returned?
+        false
+      end
+
+      def build_record(trace)
+        exception = trace.exception
+
+        RailsTracepointStack::TraceRecord.new(
+          kind: trace.kind,
+          class_name: class_name_for(trace),
+          method_name: trace.method_name,
+          file_path: trace.file_path,
+          line_number: trace.line_number,
+          params: params_for(trace),
+          return_value: return_value_for(trace),
+          exception_class: exception && exception.class.to_s,
+          exception_message: exception && RailsTracepointStack::LogFormatter.stringify(exception.message),
+          depth: trace.depth || 0,
+          repeats: 1
+        )
+      end
+
+      # `to_s` on a class is whatever that class decided to print. ActiveRecord
+      # makes a model's singleton class print its entire schema, which turns one
+      # method call into hundreds of characters of column definitions. A module
+      # knows its own name, so ask for that instead and only fall back to `to_s`
+      # for the anonymous ones that have none.
+      def class_name_for(trace)
+        klass = trace.class_name
+        return RailsTracepointStack::LogFormatter.stringify(klass) unless klass.is_a?(Module)
+
+        name = klass.name
+        return name if name
+
+        attached = attached_module(klass)
+        return "#<Class:#{attached.name}>" if attached&.name
+
+        RailsTracepointStack::LogFormatter.stringify(klass)
+      end
+
+      # Singleton classes have no name of their own. Ruby 3.2 can hand back the
+      # object they belong to; older versions leave only the printed form.
+      def attached_module(klass)
+        return nil unless klass.respond_to?(:attached_object)
+
+        attached = klass.attached_object
+        attached.is_a?(Module) ? attached : nil
+      rescue SystemStackError, StandardError
+        nil
+      end
+
+      def params_for(trace)
+        return {} unless limits.capture_params
+
+        snapshot(trace.params)
+      end
+
+      def return_value_for(trace)
+        return nil unless limits.capture_return
+
+        snapshot(trace.return_value)
+      end
+
+      def snapshot(value)
+        RailsTracepointStack::Truncator.bounded(
+          RailsTracepointStack::LogFormatter.safe_value(value),
+          limits
+        )
+      end
+    end
+  end
+end

data/lib/rails_tracepoint_stack/sink/log.rb

@@ -0,0 +1,17 @@
+require "rails_tracepoint_stack/logger"
+require "rails_tracepoint_stack/log_formatter"
+
+module RailsTracepointStack
+  module Sink
+    # Formats each trace and writes it out, which is what the gem has always
+    # done. Kept as the default so enabling the tracer globally behaves the
+    # same as before sinks existed.
+    class Log
+      def record(trace)
+        RailsTracepointStack::Logger.log(
+          RailsTracepointStack::LogFormatter.message(trace)
+        )
+      end
+    end
+  end
+end

data/lib/rails_tracepoint_stack/skill_installer.rb

@@ -0,0 +1,39 @@
+require "fileutils"
+
+module RailsTracepointStack
+  # Copies the packaged agent skill into the host app.
+  #
+  # A skill living in this gem's repository only helps someone working on the
+  # gem. Agents look for skills inside the project they are working on, so the
+  # file has to land there for the gem to ever get picked up on its own.
+  class SkillInstaller
+    SKILL_PATH = ".claude/skills/debug-with-tracepoint/SKILL.md".freeze
+    TEMPLATE_PATH = File.expand_path("templates/skill.md", __dir__).freeze
+
+    attr_reader :destination, :force
+
+    def initialize(destination: Dir.pwd, force: false)
+      @destination = destination
+      @force = force
+    end
+
+    # Returns the path written, or nil when a skill was already there.
+    def install
+      return nil if File.exist?(target_path) && !force
+
+      FileUtils.mkdir_p(File.dirname(target_path))
+      File.write(target_path, template)
+      target_path
+    end
+
+    def target_path
+      File.join(destination, SKILL_PATH)
+    end
+
+    private
+
+    def template
+      File.read(TEMPLATE_PATH)
+    end
+  end
+end

data/lib/rails_tracepoint_stack/templates/skill.md

@@ -0,0 +1,142 @@
+---
+name: debug-with-tracepoint
+description: Use when you need to know what a Ruby/Rails code path actually did at runtime - which methods ran, what arguments they got, what each one returned, and where an exception was first raised. Reach for this before adding puts/Rails.logger lines or reading call sites by hand, and whenever a value is wrong but you cannot tell which method produced it.
+---
+
+# Debugging with rails_tracepoint_stack
+
+Traces one block of code and hands back the call tree: every method your app
+defined that ran, with its arguments, its return value, and any exception,
+nested by call depth. Gems, the framework and stdlib are filtered out.
+
+## When this beats the alternatives
+
+| Question | Use this |
+|---|---|
+| "Which of these methods is returning nil?" | Yes - return values are the point |
+| "Where did this exception actually start?" | Yes - the raise is tagged in the tree |
+| "What is the real order of calls here?" | Yes - the tree shows nesting |
+| "What is the value of one variable right here?" | No - a `binding.irb` is cheaper |
+| "Is this endpoint slow?" | No - this measures nothing |
+
+## Run it
+
+One shot, no config file, no server restart, output bounded:
+
+```bash
+bin/rails runner '
+  session = RailsTracepointStack.capture(max_depth: 4) do
+    Order.find(42).recalculate!
+  end
+  puts session.to_tree
+'
+```
+
+Reading the output:
+
+```
+Order#recalculate! (app/models/order.rb:88) {}
+  Order#apply_discount (app/models/order.rb:102) {"total":200.0}
+    Discount#rate_for (app/models/discount.rb:12) {"order":"#<Order id: 42>"}
+      -> null              <- rate_for returned nil, which is the bug
+    -> 200.0
+  -> 200.0
+3 calls, 3 returns, 0 raises, 2 classes
+```
+
+- indentation is call depth
+- `-> value` is what the method on the line above returned
+- `!! ArgumentError: message` marks where an exception was raised
+- a `-> null` right after a `!!` is the frame unwinding, not a real return
+- `render app/views/...` is a template; the `{...}` after it are its locals
+- the last line is the summary; `... truncated` means a limit cut it short
+
+### An empty tree is an answer, not a failure
+
+```
+0 calls, 0 returns, 0 raises, 0 classes
+no app code ran: 34025 traces from gems, the framework and Ruby itself were filtered out
+```
+
+This means the block ran entirely inside gems. A bare `Order.where(...).map(&:name)`
+calls no method anyone in this app wrote — `name` is generated by ActiveRecord.
+Do not conclude the tool is broken and fall back to `puts`. Either widen the
+capture to include the code that calls into this, or accept that the bug is not
+in app code. `session.filtered_count` is that number if you want it directly.
+
+## Keep the output small
+
+`capture` is scoped to the calling thread and takes limits. Use them - an
+unbounded capture of a real request is tens of thousands of lines.
+
+| Option | Default | Use it to |
+|---|---|---|
+| `max_depth:` | none | Stay near the top of the tree |
+| `max_traces:` | 5000 | Cap total lines |
+| `max_string_length:` | 200 | Keep big payloads readable |
+| `max_collection_size:` | 20 | Keep loaded associations readable |
+| `max_value_length:` | 1000 | Cap any single value, whatever its shape |
+| `capture_params: false` | on | Show only the flow |
+| `capture_return: false` | on | Show only the calls |
+| `threads: :all` | current only | Include background threads |
+| `blocks: true` | off | Also trace blocks — see below |
+
+### When a scope or lambda seems to do nothing
+
+A Rails scope is a lambda, not a method, so by default nothing inside it shows
+up — you see the call that used the scope and then its result, with no steps in
+between. Same for any `yield`ed block. Add `blocks: true`:
+
+```ruby
+RailsTracepointStack.capture(blocks: true) { News.latest(User.current) }
+```
+
+Blocks render as `Class#method { }`, or as `block { }` plus a location when the
+block has no enclosing method (which is what a scope looks like). A line like
+`↻ 40× ... { }` means that block ran 40 times from the same place — a predicate
+inside a loop — and only the first run's arguments were kept.
+
+Leave it off unless you need it. A block inside a loop fires once per element,
+so this costs far more traces than watching methods does.
+
+To narrow by file instead, set patterns before capturing:
+
+```ruby
+RailsTracepointStack.configure do |config|
+  config.file_path_to_filter_patterns << %r{app/services/}
+  config.ignore_patterns << %r{app/models/concerns/}
+end
+```
+
+## Other shapes of the same data
+
+```ruby
+session.as_json    # structured: one entry per trace
+session.summary    # counts only: {calls:, returns:, raises:, classes:, truncated:}
+session.result     # what the block itself returned
+session.error      # the exception that escaped, if any
+```
+
+`capture` re-raises whatever the block raised. To keep the traces in that
+case, take the session from the block argument:
+
+```ruby
+session = nil
+begin
+  RailsTracepointStack.capture { |s| session = s; thing_that_blows_up }
+rescue => error
+  puts session.to_tree
+end
+```
+
+## Worth knowing
+
+- Requires the gem in the app: `gem "rails_tracepoint_stack"`.
+- TracePoint slows the traced block down noticeably. Fine for a one-off
+  investigation, not for anything left running.
+- Only methods defined in the app appear. If a method you expected is
+  missing, it is probably in a gem - add its path to
+  `file_path_to_filter_patterns` to force it in.
+- `RAILS_TRACEPOINT_STACK_ENABLED=true` traces the whole process to
+  `log/rails_tracepoint_stack.log` instead. Prefer `capture` unless you need
+  to trace something you cannot wrap in a block, such as boot.

data/lib/rails_tracepoint_stack/trace.rb

@@ -5,6 +5,7 @@ module RailsTracepointStack
     extend Forwardable
 
     attr_reader :params, :trace_point
+    attr_accessor :depth
 
     def_delegator :@trace_point, :defined_class, :class_name
     def_delegator :@trace_point, :method_id, :method_name
@@ -15,16 +16,45 @@ module RailsTracepointStack
       @trace_point = trace_point
     end
 
+    def kind
+      trace_point.event
+    end
+
+    ENTERING = [:call, :b_call].freeze
+    LEAVING = [:return, :b_return].freeze
+
     def params
+      return {} unless ENTERING.include?(kind)
+
       @params ||= fetch_params(trace_point)
     end
 
+    def return_value
+      return nil unless LEAVING.include?(kind)
+
+      trace_point.return_value
+    end
+
+    def exception
+      return nil unless kind == :raise
+
+      trace_point.raised_exception
+    end
+
     private
 
+    # Every local the method body declares is already in scope at :call time,
+    # holding nil. Reading the whole binding would report those as arguments
+    # the caller passed as nil, so the parameter list decides what to read.
     def fetch_params(trace_point)
-      trace_point.binding.local_variables.map { |var|
-        [var, trace_point.binding.local_variable_get(var)]
-      }.to_h
+      binding = trace_point.binding
+      declared = binding.local_variables
+
+      trace_point.parameters.each_with_object({}) do |(_type, name), params|
+        next if name.nil? || !declared.include?(name)
+
+        params[name] = binding.local_variable_get(name)
+      end
     end
   end
 end

data/lib/rails_tracepoint_stack/trace_record.rb

@@ -0,0 +1,45 @@
+module RailsTracepointStack
+  # An immutable snapshot of a single trace. The TracePoint object is only
+  # valid while its event is being handled, so anything worth keeping has to
+  # be copied out before the handler returns.
+  TraceRecord = Struct.new(
+    :kind,
+    :class_name,
+    :method_name,
+    :file_path,
+    :line_number,
+    :params,
+    :return_value,
+    :exception_class,
+    :exception_message,
+    :depth,
+    :repeats,
+    keyword_init: true
+  ) do
+    def call?
+      kind == :call
+    end
+
+    def return?
+      kind == :return
+    end
+
+    def raise?
+      kind == :raise
+    end
+
+    def block_call?
+      kind == :b_call
+    end
+
+    def block_return?
+      kind == :b_return
+    end
+
+    # True for anything that produced a value on the way out, so callers do not
+    # have to know whether a method or a block produced it.
+    def returned?
+      return? || block_return?
+    end
+  end
+end

data/lib/rails_tracepoint_stack/trace_session.rb

@@ -0,0 +1,77 @@
+require "json"
+require "rails_tracepoint_stack/renderer/summary"
+require "rails_tracepoint_stack/renderer/tree"
+
+module RailsTracepointStack
+  # The traces gathered by one capture, plus whatever the traced block itself
+  # produced.
+  class TraceSession
+    attr_reader :traces
+    attr_accessor :result, :error, :filtered_count
+    attr_writer :truncated
+
+    def initialize
+      @traces = []
+      @truncated = false
+      @filtered_count = 0
+    end
+
+    def add(record)
+      @traces << record
+    end
+
+    def empty?
+      @traces.empty?
+    end
+
+    # True when a limit stopped the collection, so the traces are a prefix of
+    # what actually ran rather than the whole story.
+    def truncated?
+      @truncated
+    end
+
+    def to_tree
+      RailsTracepointStack::Renderer::Tree.call(self)
+    end
+    alias_method :to_s, :to_tree
+
+    def summary
+      RailsTracepointStack::Renderer::Summary.call(self)
+    end
+
+    def as_json
+      {
+        summary: summary,
+        traces: traces.map { |record| entry_for(record) }
+      }
+    end
+
+    def to_json(*args)
+      JSON.generate(as_json, *args)
+    end
+
+    private
+
+    def entry_for(record)
+      entry = {
+        kind: record.kind,
+        depth: record.depth,
+        class_name: record.class_name,
+        method_name: record.method_name,
+        file_path: "#{RailsTracepointStack::Renderer::Tree.relative_path(record.file_path)}:#{record.line_number}",
+        params: record.params
+      }
+
+      # A method that returned nil is often the answer being looked for, so
+      # the key stays even when there is nothing in it.
+      entry[:return_value] = record.return_value if record.return?
+
+      if record.raise?
+        entry[:exception_class] = record.exception_class
+        entry[:exception_message] = record.exception_message
+      end
+
+      entry
+    end
+  end
+end