rails_tracepoint_stack 0.3.4 → 0.4.0

data/lib/rails_tracepoint_stack/logger.rb

@@ -5,7 +5,7 @@ module RailsTracepointStack
         RailsTracepointStack.configuration.logger.info(msg)
       else
         # TODO: Add the support to Rails.env for the default filename
-        File.open("log/rails_tracepoint_stack.log", 'a') do |f|
+        File.open("log/rails_tracepoint_stack.log", "a") do |f|
           f.puts msg
         end
       end

data/lib/rails_tracepoint_stack/renderer/summary.rb

@@ -0,0 +1,37 @@
+module RailsTracepointStack
+  module Renderer
+    # Counts what a session holds, so a reader can tell at a glance whether
+    # the capture saw what they expected before reading the tree itself.
+    module Summary
+      def self.call(session)
+        {
+          calls: count(session, :call),
+          returns: count(session, :return),
+          raises: count(session, :raise),
+          classes: session.traces.map(&:class_name).uniq.size,
+          filtered: session.filtered_count,
+          truncated: session.truncated?
+        }
+      end
+
+      def self.line(session)
+        counts = call(session)
+
+        [
+          pluralize(counts[:calls], "call"),
+          pluralize(counts[:returns], "return"),
+          pluralize(counts[:raises], "raise"),
+          pluralize(counts[:classes], "class", "classes")
+        ].join(", ")
+      end
+
+      def self.count(session, kind)
+        session.traces.count { |record| record.kind == kind }
+      end
+
+      def self.pluralize(count, singular, plural = "#{singular}s")
+        "#{count} #{(count == 1) ? singular : plural}"
+      end
+    end
+  end
+end

data/lib/rails_tracepoint_stack/renderer/tree.rb

@@ -0,0 +1,115 @@
+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 :return then return_line(record)
+        when :raise then raise_line(record)
+        end
+      end
+
+      SINGLETON_CLASS = /\A#<Class:([A-Z][\w:]*)>\z/
+      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,69 @@
+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
+      end
+
+      def record(trace)
+        return if limits.too_deep?(trace.depth)
+
+        unless limits.room_for?(session.traces.size)
+          session.truncated = true
+          return
+        end
+
+        session.add(build_record(trace))
+      end
+
+      private
+
+      def build_record(trace)
+        exception = trace.exception
+
+        RailsTracepointStack::TraceRecord.new(
+          kind: trace.kind,
+          class_name: RailsTracepointStack::LogFormatter.stringify(trace.class_name),
+          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
+        )
+      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.call(
+          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,122 @@
+---
+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 |
+| `capture_params: false` | on | Show only the flow |
+| `capture_return: false` | on | Show only the calls |
+| `threads: :all` | current only | Include background threads |
+
+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

@@ -1,10 +1,11 @@
-require 'forwardable'
+require "forwardable"
 
 module RailsTracepointStack
   class Trace
     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,42 @@ module RailsTracepointStack
       @trace_point = trace_point
     end
 
+    def kind
+      trace_point.event
+    end
+
     def params
+      return {} unless kind == :call
+
       @params ||= fetch_params(trace_point)
     end
 
+    def return_value
+      return nil unless kind == :return
+
+      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_filter.rb

@@ -22,7 +22,7 @@ module RailsTracepointStack
       end
       if should_ignore_because_is_ruby_trace?(trace: trace)
         return true
-      end 
+      end
 
       return false
     end

data/lib/rails_tracepoint_stack/trace_record.rb

@@ -0,0 +1,30 @@
+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,
+    keyword_init: true
+  ) do
+    def call?
+      kind == :call
+    end
+
+    def return?
+      kind == :return
+    end
+
+    def raise?
+      kind == :raise
+    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

data/lib/rails_tracepoint_stack/tracer.rb

@@ -1,23 +1,82 @@
-#TODO: Move to a loader file
-require 'rails_tracepoint_stack/logger'
-require 'rails_tracepoint_stack/trace_filter'
-require 'rails_tracepoint_stack/trace'
-require 'rails_tracepoint_stack/log_formatter'
+# TODO: Move to a loader file
+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
-    # TODO: Tracer.new shoud return the tracer. Is weird to call Tracer.new.tracer
-    def tracer
-      @tracer ||= TracePoint.new(:call) do |tracepoint|
+    extend Forwardable
+
+    DEFAULT_EVENTS = [:call].freeze
+
+    def_delegators :@tracer, :enable, :disable
+
+    # 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.
+    def initialize(sink: RailsTracepointStack::Sink::Log.new, events: DEFAULT_EVENTS, thread: nil)
+      @sink = sink
+      @events = events
+      @thread = thread
+      @filtered_count = 0
+      generate_tracer
+    end
+
+    private
+
+    def generate_tracer
+      @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)
+        if ignore_trace?(trace: trace)
+          @filtered_count += 1
+          next
+        end
+
+        trace.depth = depth_for(trace)
+        @sink.record(trace)
+      end
+    end
+
+    def out_of_scope_thread?
+      !@thread.nil? && Thread.current != @thread
+    end
 
-        # TODO: Use proper OO
-        message = RailsTracepointStack::LogFormatter.message trace
-        RailsTracepointStack::Logger.log message 
+    # 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 then tracker.enter(raw_position)
+      when :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