rails_tracepoint_stack 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 612ce09f08d0dfebf77cfddc8dfbe9712598aaf324579f688bac6148354c92fb
-  data.tar.gz: aec94f6a1a148f16199b6835932a5b1fe91ff458a2915fab60efe937244b7cac
+  metadata.gz: 7853cf9027a5db8f962c4cf6753ae98cac10e3cdd0344b618fac59a112837e6d
+  data.tar.gz: 29beeae6b2e5eacbca3121a90bef1670e759477b5cfc48aa837dba6ebcb48fe0
 SHA512:
-  metadata.gz: de2e858cfad1406ee8becdb5d3be65b956286c802a1f95023d8698eaa80500569ee603be1b28e06404845a41eebb25e364ea936cdd886fcdab02b14113caaf10
-  data.tar.gz: 17b4beea42cb83b2058b32652acf0ddeec66a1b2fabe32e61a07fcf446738fd4c92b238dd6ce603d5426d68af4e1bbe397e23c7afd7c739c4385ed3d8cf61177
+  metadata.gz: 49af2952c9312ea180cbf2afde354b1d9c68a0a4f6d94a991534e8f19b6fed4f477afda01cdb4d93e766751a9195f183f12f93c0fdd51705b3c984127271cb7c
+  data.tar.gz: 79ff4005947c9a73f08dc03261894e6044653c3e8e1979043546e56425d0fb718587562707957c868c55930ad02606fca3abe5edd29d19b9d1b57d0b4b69938c

data/README.md

@@ -100,14 +100,44 @@ A real request produces tens of thousands of traces, so captures are bounded.
 | `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 |
+| `max_value_length` | 1000 | Replaces any single value larger than this with its size |
 | `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 |
+| `blocks` | `false` | `true` also traces blocks — see below |
 
 ```ruby
 RailsTracepointStack.capture(max_depth: 3, capture_return: false) { ... }
 ```
 
+### Blocks and scopes
+
+A Rails scope is a lambda, so the logic inside it is not a method call and does
+not appear by default. `blocks: true` traces block entry and exit as well:
+
+```ruby
+RailsTracepointStack.capture(blocks: true) { News.latest(User.current) }
+```
+
+```
+News.latest (app/models/news.rb:88) {"user":"Anonymous"}
+  block { } (app/models/news.rb:46) {"user":"Anonymous"}
+    Project.allowed_to_condition (app/models/project.rb:189) {"permission":"view_news"}
+      ↻ 40× AccessControl.permission { } (lib/redmine/access_control.rb:37) {"p":"#<Permission …>"}
+        -> false
+```
+
+It is off by default because a block written inside a loop runs once per
+element: in Redmine, one call produced 48 block events and 43 of them came from
+a single `detect` predicate. Runs of the same block at the same depth collapse
+into one line with a `↻ N×` count, which keeps only the first run's arguments —
+if you need every iteration, leave blocks off and read the loop instead.
+
+Blocks are named after the method they were written in. A block with no
+enclosing method — a scope, a lambda held in a constant — has neither a class
+nor a method name to show, so it renders as `block { }` plus its location.
+```
+
 ## Tracing the whole process
 
 For code you cannot wrap in a block — boot, a rake task, a request handled by a

data/changelog.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.5.0
+
+**Features**
+
+- `capture(blocks: true)` traces block entry and exit, which is what makes a
+  Rails scope, a lambda held in a constant, or any yielded block visible.
+  Off by default: a block inside a loop runs once per element. Runs of the
+  same block at the same depth collapse into one record with a `↻ N×` count
+- `max_value_length` (default 1000) caps any single value, whatever its shape
+
+**BugFix**
+
+- `to_tree` raised `Encoding::CompatibilityError` whenever a traced value held
+  bytes that are not text — a file read in binary mode, a digest, a response
+  body. Strings are now converted to UTF-8 with invalid bytes replaced
+- A class method on an ActiveRecord model rendered as its singleton class,
+  which prints the model's entire schema for a single call. The class name now
+  comes from the module's own name
+- Per-string and per-collection limits still let one value through at thousands
+  of characters, since twenty items truncated to two hundred each is four
+  thousand
+- The block handed to `capture` was traced as part of the result and consumed a
+  level of depth, indenting everything under it
+
 ## 0.4.0
 
 **Features**

data/lib/rails_tracepoint_stack/limits.rb

@@ -6,11 +6,13 @@ module RailsTracepointStack
     DEFAULT_MAX_TRACES = 5_000
     DEFAULT_MAX_STRING_LENGTH = 200
     DEFAULT_MAX_COLLECTION_SIZE = 20
+    DEFAULT_MAX_VALUE_LENGTH = 1_000
 
     attr_reader :max_depth,
       :max_traces,
       :max_string_length,
       :max_collection_size,
+      :max_value_length,
       :capture_params,
       :capture_return
 
@@ -19,6 +21,7 @@ module RailsTracepointStack
       max_traces: DEFAULT_MAX_TRACES,
       max_string_length: DEFAULT_MAX_STRING_LENGTH,
       max_collection_size: DEFAULT_MAX_COLLECTION_SIZE,
+      max_value_length: DEFAULT_MAX_VALUE_LENGTH,
       capture_params: true,
       capture_return: true
     )
@@ -26,6 +29,7 @@ module RailsTracepointStack
       @max_traces = max_traces
       @max_string_length = max_string_length
       @max_collection_size = max_collection_size
+      @max_value_length = max_value_length
       @capture_params = capture_params
       @capture_return = capture_return
     end

data/lib/rails_tracepoint_stack/log_formatter.rb

@@ -25,14 +25,36 @@ module RailsTracepointStack
       )
     end
 
+    REPLACEMENT = "�".freeze
+
     def self.stringify(value)
       return nil if value.nil?
 
-      value.to_s
+      utf8(value.to_s)
     rescue SystemStackError, StandardError => error
       inspect_fallback(value, error)
     end
 
+    # Traced code holds bytes that are not text: a file read in binary mode, a
+    # digest, a response body. Left as they are, those strings poison every
+    # consumer downstream - JSON refuses to encode them, and joining them with
+    # the rest of the output raises Encoding::CompatibilityError. Normalizing
+    # here keeps the damage to the one value that caused it.
+    def self.utf8(value)
+      return value unless value.is_a?(String)
+
+      converted =
+        if value.encoding == Encoding::UTF_8
+          value
+        else
+          value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: REPLACEMENT)
+        end
+
+      converted.valid_encoding? ? converted : converted.scrub(REPLACEMENT)
+    rescue SystemStackError, StandardError
+      value.scrub(REPLACEMENT)
+    end
+
     def self.safe_value(value, ancestry = {})
       case value
       when nil, true, false, Numeric
@@ -40,7 +62,7 @@ module RailsTracepointStack
       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
+        utf8(value).dup.freeze
       when Symbol
         value.to_s
       when Array
@@ -125,7 +147,7 @@ module RailsTracepointStack
     end
 
     def self.safe_object_string(value)
-      value.inspect
+      utf8(value.inspect)
     rescue SystemStackError, StandardError => error
       inspect_fallback(value, error)
     end
@@ -146,7 +168,7 @@ module RailsTracepointStack
       when true, false, Numeric
         value.to_s
       when String
-        value.inspect
+        utf8(value).inspect
       when Symbol
         ":#{value}"
       when Array

data/lib/rails_tracepoint_stack/renderer/tree.rb

@@ -32,12 +32,39 @@ module RailsTracepointStack
       def self.line_for(record)
         case record.kind
         when :call then call_line(record)
-        when :return then return_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
 
-      SINGLETON_CLASS = /\A#<Class:([A-Z][\w:]*)>\z/
+      # 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.

data/lib/rails_tracepoint_stack/sink/collector.rb

@@ -14,6 +14,8 @@ module RailsTracepointStack
       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)
@@ -24,17 +26,54 @@ module RailsTracepointStack
           return
         end
 
-        session.add(build_record(trace))
+        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: RailsTracepointStack::LogFormatter.stringify(trace.class_name),
+          class_name: class_name_for(trace),
           method_name: trace.method_name,
           file_path: trace.file_path,
           line_number: trace.line_number,
@@ -42,10 +81,40 @@ module RailsTracepointStack
           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
+          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
 
@@ -59,7 +128,7 @@ module RailsTracepointStack
       end
 
       def snapshot(value)
-        RailsTracepointStack::Truncator.call(
+        RailsTracepointStack::Truncator.bounded(
           RailsTracepointStack::LogFormatter.safe_value(value),
           limits
         )

data/lib/rails_tracepoint_stack/templates/skill.md

@@ -75,9 +75,29 @@ unbounded capture of a real request is tens of thousands of lines.
 | `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:
 

data/lib/rails_tracepoint_stack/trace.rb

@@ -20,14 +20,17 @@ module RailsTracepointStack
       trace_point.event
     end
 
+    ENTERING = [:call, :b_call].freeze
+    LEAVING = [:return, :b_return].freeze
+
     def params
-      return {} unless kind == :call
+      return {} unless ENTERING.include?(kind)
 
       @params ||= fetch_params(trace_point)
     end
 
     def return_value
-      return nil unless kind == :return
+      return nil unless LEAVING.include?(kind)
 
       trace_point.return_value
     end

data/lib/rails_tracepoint_stack/trace_record.rb

@@ -13,6 +13,7 @@ module RailsTracepointStack
     :exception_class,
     :exception_message,
     :depth,
+    :repeats,
     keyword_init: true
   ) do
     def call?
@@ -26,5 +27,19 @@ module RailsTracepointStack
     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/tracer.rb

@@ -23,10 +23,22 @@ module RailsTracepointStack
     # 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)
+    # 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
@@ -39,6 +51,8 @@ module RailsTracepointStack
 
         trace = RailsTracepointStack::Trace.new(trace_point: tracepoint)
 
+        next if own_block?(trace)
+
         if ignore_trace?(trace: trace)
           @filtered_count += 1
           next
@@ -49,6 +63,35 @@ module RailsTracepointStack
       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?
+
+      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
@@ -61,8 +104,8 @@ module RailsTracepointStack
       raw_position = raw_stack_position
 
       case trace.kind
-      when :call then tracker.enter(raw_position)
-      when :return then tracker.leave(raw_position)
+      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

data/lib/rails_tracepoint_stack/truncator.rb

@@ -1,3 +1,5 @@
+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
@@ -6,6 +8,39 @@ module RailsTracepointStack
   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)

data/lib/rails_tracepoint_stack/version.rb

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

data/lib/rails_tracepoint_stack.rb

@@ -22,11 +22,16 @@ module RailsTracepointStack
   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.
-  def self.capture(threads: :current, **limit_options)
-    raise ArgumentError, "Block not given to #capture" unless block_given?
+  # 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)
@@ -34,13 +39,14 @@ module RailsTracepointStack
     session = collector.session
     tracer = RailsTracepointStack::Tracer.new(
       sink: collector,
-      events: CAPTURE_EVENTS,
-      thread: (threads == :all) ? nil : Thread.current
+      events: blocks ? CAPTURE_EVENTS + BLOCK_EVENTS : CAPTURE_EVENTS,
+      thread: (threads == :all) ? nil : Thread.current,
+      own_block: traced
     )
 
     tracer.enable
     begin
-      session.result = yield(session)
+      session.result = traced.call(session)
     rescue Exception => error
       session.error = error
       raise

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_tracepoint_stack
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Carlos Daniel Pohlod
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-24 00:00:00.000000000 Z
+date: 2026-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec