rails_tracepoint_stack 0.3.5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f67c982828a7ad060513cbb50daf9f88399229a534a43cf12a674571b6ae11ae
-  data.tar.gz: fd80c178bf9de58408e769742d7640b0ccdbcc99a4722ec9ccbd6e68d115ff51
+  metadata.gz: 612ce09f08d0dfebf77cfddc8dfbe9712598aaf324579f688bac6148354c92fb
+  data.tar.gz: aec94f6a1a148f16199b6835932a5b1fe91ff458a2915fab60efe937244b7cac
 SHA512:
-  metadata.gz: 57b7125a7a242bf59f15096fffeef7de3c8a7543162fa7851566a07256d2ed790d39ff9c9dfcd1f3c3f8ca54714b797ed5f5015f2eb0d6f0adbe57e3ad582412
-  data.tar.gz: cd33cf3e53fe35fe62ba3867cfe8ff56047cceae59e2139c55898fcb0ed0e44d8dccf57a0b66954f1543797c1cb1070b6c68f479f76ce80f0c15282518c50110
+  metadata.gz: de2e858cfad1406ee8becdb5d3be65b956286c802a1f95023d8698eaa80500569ee603be1b28e06404845a41eebb25e364ea936cdd886fcdab02b14113caaf10
+  data.tar.gz: 17b4beea42cb83b2058b32652acf0ddeec66a1b2fabe32e61a07fcf446738fd4c92b238dd6ce603d5426d68af4e1bbe397e23c7afd7c739c4385ed3d8cf61177

data/README.md

@@ -0,0 +1,174 @@
+# rails_tracepoint_stack
+
+**[carlosdanielpohlod.github.io/rails_tracepoint_stack](https://carlosdanielpohlod.github.io/rails_tracepoint_stack/)**
+
+See what your Rails code actually did at runtime: which of *your* methods ran,
+what arguments they got, what each one returned, and where an exception was
+first raised — as a call tree, with gems, the framework and stdlib filtered out.
+
+```ruby
+session = RailsTracepointStack.capture(max_depth: 4) do
+  Order.find(42).recalculate!
+end
+
+puts session.to_tree
+```
+
+```
+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
+    -> 200.0
+  -> 200.0
+3 calls, 3 returns, 0 raises, 2 classes
+```
+
+`rate_for` returned nil. No `puts`, no log file, no restart.
+
+A whole Rails request comes out about this long, because everything the
+framework runs underneath is filtered away:
+
+```
+RealEstateAgenciesController#index (app/controllers/real_estate_agencies_controller.rb:14) {}
+  IpLocation.guess_state_uf_and_city_name (app/services/ip_location.rb:15) {"ip":"127.0.0.1"}
+    -> [null,null]
+  -> null
+render app/views/real_estate_agencies/index.html.erb {}
+  -> "<!-- BEGIN app/views/real_estate_agencies/index.html.erb\n-->… (2507 chars)"
+4 calls, 4 returns, 0 raises, 3 classes
+```
+
+That is 4 kept traces out of 13869 the tracer saw.
+
+## Install
+
+```ruby
+# Gemfile
+gem "rails_tracepoint_stack"
+```
+
+## Debugging with an AI agent
+
+Agents reach for `puts` and log lines because they do not know this exists.
+Install the packaged skill into your app and yours will use the gem instead:
+
+```bash
+bin/rails generate rails_tracepoint_stack:install
+```
+
+That writes `.claude/skills/debug-with-tracepoint/SKILL.md`, which tells the
+agent when tracing beats reading code, how to keep the output inside its
+context window, and how to read the tree. Pass `--force` to overwrite an
+existing copy.
+
+## Capturing
+
+`capture` traces the block, returns a session and re-raises anything the block
+raised. It watches only the calling thread, so it stays clean under Puma.
+
+```ruby
+session = RailsTracepointStack.capture { Order.find(42).recalculate! }
+
+session.to_tree    # the indented call tree above
+session.as_json    # the same data, structured, one entry per trace
+session.summary    # {calls:, returns:, raises:, classes:, truncated:}
+session.result     # what the block returned
+session.error      # the exception that escaped, if any
+session.traces     # the raw TraceRecord list
+```
+
+To keep the traces when the block blows up, 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
+```
+
+### Keeping the output small
+
+A real request produces tens of thousands of traces, so captures are bounded.
+
+| Option | Default | What it does |
+|---|---|---|
+| `max_depth` | none | Drops traces nested deeper than this |
+| `max_traces` | 5000 | Stops collecting; `session.truncated?` becomes true |
+| `max_string_length` | 200 | Shortens long strings |
+| `max_collection_size` | 20 | Shortens long arrays and hashes |
+| `capture_params` | `true` | Set false to show only the flow |
+| `capture_return` | `true` | Set false to show only the calls |
+| `threads` | `:current` | `:all` also records background threads |
+
+```ruby
+RailsTracepointStack.capture(max_depth: 3, capture_return: false) { ... }
+```
+
+## Tracing the whole process
+
+For code you cannot wrap in a block — boot, a rake task, a request handled by a
+running server — enable the tracer globally instead. Output goes to
+`log/rails_tracepoint_stack.log`.
+
+```bash
+RAILS_TRACEPOINT_STACK_ENABLED=true bin/rails server
+```
+
+```
+called: Bar#perform in /path/to/app/services/bar.rb:12 with params: {}
+```
+
+`RailsTracepointStack.enable_trace { ... }` does the same for one block, also
+writing to the log rather than returning a session.
+
+## Configuration
+
+```ruby
+# config/initializers/rails_tracepoint_stack.rb
+
+RailsTracepointStack.configure do |config|
+  config.file_path_to_filter_patterns << %r{app/services/}
+  config.ignore_patterns << %r{app/models/concerns/}
+  config.log_format = :json
+  config.log_external_sources = false
+  config.logger = Rails.logger
+end
+```
+
+| Configuration | Description |
+|---|---|
+| `file_path_to_filter_patterns` | Trace **only** files whose path matches one of these patterns |
+| `ignore_patterns` | Skip traces whose file path matches one of these patterns |
+| `log_format` | `:text` (default) or `:json`. Applies to the log, not to `capture` |
+| `log_external_sources` | Include gems, bundler and stdlib. Default `false` |
+| `logger` | Your own logger. Defaults to `log/rails_tracepoint_stack.log` |
+
+A method missing from a trace is usually one the filters dropped as external —
+add its path to `file_path_to_filter_patterns` to force it in.
+
+## Worth knowing
+
+- TracePoint makes the traced code noticeably slower — around 8x on a real
+  Rails request. Fine for an investigation, not for something left running in
+  production.
+- Ruby >= 3.0.
+- A `-> null` line directly under a `!!` line is the frame unwinding, not a
+  method that returned nil.
+- An empty tree says `no app code ran` along with how much was filtered. That
+  usually means the block ran entirely inside gems — `Order.where(...).map(&:name)`
+  calls no method you wrote, since `name` is generated by ActiveRecord.
+
+## Links
+
+- [Website](https://carlosdanielpohlod.github.io/rails_tracepoint_stack/) — the
+  same story with real captured output, including a whole Rails request
+- [RubyGems](https://rubygems.org/gems/rails_tracepoint_stack)
+- [Changelog](changelog.md)
+
+## License
+
+MIT

data/changelog.md

@@ -0,0 +1,132 @@
+# Changelog
+
+## 0.4.0
+
+**Features**
+
+- `RailsTracepointStack.capture` traces a block and returns the traces in
+  memory, with no env var, log file or restart involved
+- Traces now carry return values and raised exceptions, not just calls and params
+- Each trace knows its call depth, so a session renders as a call tree
+- `session.to_tree`, `session.as_json` and `session.summary` render a capture
+- Captures are bounded by `max_depth`, `max_traces`, `max_string_length` and
+  `max_collection_size`, and report `truncated?` when a limit cut them short
+- Captures watch only the calling thread by default; `threads: :all` opts out
+- `rails g rails_tracepoint_stack:install` writes an agent skill into the app,
+  so AI coding agents know when and how to trace it
+
+**BugFix**
+
+- Params reported every local the method body declared, not just the arguments
+  it received, so unassigned locals showed up as arguments passed as nil.
+  `TracePoint#parameters` now decides what is read from the binding
+- `GemPath` referenced `Bundler` without requiring it, raising `NameError` on
+  the first trace outside a bundle
+- A raise coming out of a C method landed one level too deep in the tree
+
+**Changes**
+
+- The tracer writes to a sink; the default one keeps the previous logging
+  behaviour, so global tracing is unchanged
+- Class methods render as `Foo.bar` rather than `#<Class:Foo>#bar`
+- Compiled templates render as `render app/views/…` with their locals, instead
+  of the generated method name and the rendering internals
+- An empty capture reports how many traces the filters dropped, so "nothing
+  ran" is distinguishable from "nothing of yours ran"
+- Serialized string values are frozen copies, so a snapshot no longer follows
+  later mutations of the traced object
+
+## 0.3.5
+
+**BugFix**
+
+- Sanitize traced params before formatting so JSON logging does not overflow on recursive or problematic objects [Issue #37](https://github.com/carlosdanielpohlod/rails_tracepoint_stack/issues/37)
+- Stabilize text log param rendering across Ruby versions
+
+## 0.3.4
+
+**Changes**
+
+- Fix flaky tests by @danielmbrasil [PR #27](https://github.com/carlosdanielpohlod/rails_tracepoint_stack/pull/27)
+
+- Huge refactor of filters class, separating in modules by filter type [PR #18](https://github.com/carlosdanielpohlod/rails_tracepoint_stack/pull/18)
+
+- Some other code refactors
+
+## 0.3.3
+
+**Changes**
+
+- Add autoload of all lib files on test_helper
+- Fix some tests
+
+**BugFix**
+
+- Fixed the Configuration module not loading the default value for the configuration attributes
+
+## 0.3.1
+
+**Changes:**
+
+- Add the ability to include the external sources to the log using `config.log_external_sources = true`
+
+## 0.3.0
+
+**Changes:**
+
+- Refactor classes, formatting a trace using a value object class `RailsTracepointStack::Trace`
+- include configuration `log_format` option, allowing choose an output as `text` or `json`
+- Include configuration `file_path_to_filter_patterns`, allowing filter traces only when the origin file path matches a pattern
+- Improve test coverage
+
+## 0.2.1
+
+**Changes:**
+
+- Update the ENV enable to be more semantic
+- Add the VERSION constant module
+- Sorted the files inside of gemspec
+- Fix the depencies on the gemspec
+- Add the "log_format" configuration support for text and json formats
+
+## 0.2.0
+
+**Changes:**
+
+- Refactor by separating Logger and Filter into their own classes.
+
+- Introduce `RailsTracepointStack.configure`, which allows ignoring traces with a custom pattern and customizing the logs output. Example:
+
+```ruby
+RailsTracepointStack.configure do |config|
+  config.ignore_patterns << /services\/foo.rb/
+  config.logger = YourLogger
+end
+```
+
+The default log destination is a file located on `log/rails_tracepoint_stack.log`
+
+- Add The possibility of enable the tracer locally, by calling:
+
+```ruby
+class Foo
+  def bar
+    RailsTracepointStack.enable_trace do
+      p "your code"
+    end
+  end
+end
+```
+
+- Add Rspec and Rake development dependencies, and add partial test coverage.
+
+## 0.1.4
+
+**Changes:**
+
+- Ignore logs containing `gems/bundler`.
+- Require ruby >= 3.0.
+
+**Breaking Changes:**
+
+- To enable logs catch, it is necessary to set `RAILS_TRACEPOINT_STACK` as `true`.

data/lib/generators/rails_tracepoint_stack/install/install_generator.rb

@@ -0,0 +1,29 @@
+require "rails/generators/base"
+require "rails_tracepoint_stack/skill_installer"
+
+module RailsTracepointStack
+  module Generators
+    # Thin wrapper over SkillInstaller so the behaviour stays testable without
+    # booting Rails.
+    class InstallGenerator < Rails::Generators::Base
+      desc "Installs the debug-with-tracepoint skill so agents working in " \
+           "this app know how to trace it"
+
+      def install_agent_skill
+        installer = RailsTracepointStack::SkillInstaller.new(
+          destination: destination_root,
+          force: options[:force]
+        )
+        written = installer.install
+
+        if written
+          say_status :create, relative_to_original_destination_root(written), :green
+        else
+          say_status :skip,
+            "#{relative_to_original_destination_root(installer.target_path)} already exists (--force to replace)",
+            :yellow
+        end
+      end
+    end
+  end
+end

data/lib/rails_tracepoint_stack/depth_tracker.rb

@@ -0,0 +1,54 @@
+module RailsTracepointStack
+  # Turns raw stack positions into app-level nesting.
+  #
+  # Counting :call and :return events would not work here, for two reasons.
+  # Most frames between two traced methods belong to gems and get filtered out,
+  # so an event counter would indent app code by the depth of the framework
+  # underneath it. And the tracer does not always watch :return at all - the
+  # global tracer only subscribes to :call - so nothing would ever pop.
+  #
+  # Reading the real stack position of each kept trace avoids both. A frame
+  # recorded at an equal or deeper position has necessarily finished, whether
+  # it returned, raised, or was abandoned, so it gets dropped on the next
+  # event rather than waiting for one that may never arrive.
+  class DepthTracker
+    def initialize
+      @stack = []
+    end
+
+    def enter(raw_position)
+      drop_finished_frames(raw_position, inclusive: true)
+      depth = @stack.size
+      @stack.push(raw_position)
+      depth
+    end
+
+    def leave(raw_position)
+      drop_finished_frames(raw_position, inclusive: false)
+      return @stack.size unless @stack.last == raw_position
+
+      @stack.pop
+      @stack.size
+    end
+
+    # A raise belongs to the innermost frame being tracked. It may report a
+    # position deeper than that frame when the exception comes out of a C
+    # method the app called, such as an arithmetic coercion, and there is no
+    # tracked frame down there to attribute it to.
+    def raised(raw_position)
+      drop_finished_frames(raw_position, inclusive: false)
+
+      [@stack.size - 1, 0].max
+    end
+
+    private
+
+    def drop_finished_frames(raw_position, inclusive:)
+      if inclusive
+        @stack.pop while @stack.last && @stack.last >= raw_position
+      else
+        @stack.pop while @stack.last && @stack.last > raw_position
+      end
+    end
+  end
+end

data/lib/rails_tracepoint_stack/filter/gem_path.rb

@@ -1,8 +1,27 @@
 module RailsTracepointStack
   module Filter
     class GemPath
+      # Bundler gives the tightest answer, but it is not always there: a plain
+      # `ruby -e` or an irb session against an installed gem has no bundle, and
+      # asking Bundler then raises instead of filtering. Falling back to every
+      # installed gem is wider than needed and still filters out the code the
+      # developer did not write.
       def self.full_gem_path
-        @full_gem_path ||= Bundler.load.specs.map(&:full_gem_path)
+        @full_gem_path ||= bundled_gem_paths || gem_install_roots
+      end
+
+      def self.bundled_gem_paths
+        return nil unless defined?(::Bundler)
+
+        ::Bundler.load.specs.map(&:full_gem_path)
+      rescue
+        nil
+      end
+
+      # Without a bundle there is no resolved list to ask for, but everything
+      # installed lives under these roots, which is all the filter needs.
+      def self.gem_install_roots
+        Gem.path.map { |dir| File.join(dir, "gems") }
       end
     end
   end

data/lib/rails_tracepoint_stack/limits.rb

@@ -0,0 +1,41 @@
+module RailsTracepointStack
+  # How much a capture is allowed to keep. The defaults aim at an output a
+  # person or an agent can read in one go rather than at completeness: a
+  # single Rails request can easily produce tens of thousands of traces.
+  class Limits
+    DEFAULT_MAX_TRACES = 5_000
+    DEFAULT_MAX_STRING_LENGTH = 200
+    DEFAULT_MAX_COLLECTION_SIZE = 20
+
+    attr_reader :max_depth,
+      :max_traces,
+      :max_string_length,
+      :max_collection_size,
+      :capture_params,
+      :capture_return
+
+    def initialize(
+      max_depth: nil,
+      max_traces: DEFAULT_MAX_TRACES,
+      max_string_length: DEFAULT_MAX_STRING_LENGTH,
+      max_collection_size: DEFAULT_MAX_COLLECTION_SIZE,
+      capture_params: true,
+      capture_return: true
+    )
+      @max_depth = max_depth
+      @max_traces = max_traces
+      @max_string_length = max_string_length
+      @max_collection_size = max_collection_size
+      @capture_params = capture_params
+      @capture_return = capture_return
+    end
+
+    def too_deep?(depth)
+      !max_depth.nil? && !depth.nil? && depth > max_depth
+    end
+
+    def room_for?(count)
+      max_traces.nil? || count < max_traces
+    end
+  end
+end

data/lib/rails_tracepoint_stack/log_formatter.rb

@@ -35,8 +35,12 @@ module RailsTracepointStack
 
     def self.safe_value(value, ancestry = {})
       case value
-      when nil, true, false, Numeric, String
+      when nil, true, false, Numeric
         value
+      when String
+        # Callers may keep the result around after the traced code moved on,
+        # so a live reference to a mutable string would drift.
+        value.frozen? ? value : value.dup.freeze
       when Symbol
         value.to_s
       when Array

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

@@ -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,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_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

@@ -3,30 +3,80 @@ 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.
+    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(: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)
+        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
+
+    # 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
 
-        # TODO: Use proper OO
-        message = RailsTracepointStack::LogFormatter.message trace
-        RailsTracepointStack::Logger.log message
+      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

data/lib/rails_tracepoint_stack/truncator.rb

@@ -0,0 +1,50 @@
+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
+
+    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.4.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,37 @@ module RailsTracepointStack
     yield(configuration)
   end
 
+  CAPTURE_EVENTS = [:call, :return, :raise].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.
+  def self.capture(threads: :current, **limit_options)
+    raise ArgumentError, "Block not given to #capture" unless block_given?
+
+    collector = RailsTracepointStack::Sink::Collector.new(
+      limits: RailsTracepointStack::Limits.new(**limit_options)
+    )
+    session = collector.session
+    tracer = RailsTracepointStack::Tracer.new(
+      sink: collector,
+      events: CAPTURE_EVENTS,
+      thread: (threads == :all) ? nil : Thread.current
+    )
+
+    tracer.enable
+    begin
+      session.result = yield(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.4.0
 platform: ruby
 authors:
 - Carlos Daniel Pohlod
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-17 00:00:00.000000000 Z
+date: 2026-07-24 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: []