Traceologist is a Ruby gem that traces method call sequences using TracePoint, returning a structured, human-readable log of calls, arguments, and return values.

It is designed for debugging and understanding runtime behavior — drop it into any block of code and get a clear picture of what methods were called, with what arguments, and what they returned.

Add to your Gemfile:

gem "traceologist"

Or install directly:

gem install traceologist

require "traceologist"

class Order
  def initialize(items)
    @items = items
  end

  def total
    @items.sum { |item| item[:price] }
  end
end

result = Traceologist.trace_sequence(filter: "Order") do
  order = Order.new([{ price: 100 }, { price: 250 }])
  order.total
end

puts result

Output:

-> Order(#1)#initialize
    items: [{:price=>100}, {:price=>250}]
<- Order(#1)#initialize
    => Order(#1)
-> Order(#1)#total
<- Order(#1)#total
    => 350

Pass a class name prefix (or an array of prefixes) to exclude noise from the trace:

Traceologist.trace_sequence(filter: "MyApp") { ... }
Traceologist.trace_sequence(filter: ["MyApp::Order", "MyApp::Item"]) { ... }

Without a filter, all Ruby method calls within the block are traced.

Traceologist.trace_sequence(depth_limit: 5, filter: "MyClass") { ... }

result = Traceologist.trace_sequence(filter: "MyClass", show_locations: true) do
  MyClass.new.run
end

Output includes a comment on each call line:

-> MyClass(#1)#run # /path/to/my_class.rb:12

Each element of the returned array is a string. The lines follow this format:

#N is a stable sequence number assigned to each unique object instance within the traced block. The same object always gets the same number, making it easy to follow a single instance across many calls.

Primitive values (Integer, Float, String, Symbol, nil, true, false) are shown with inspect. All other objects are shown as ClassName(#N).

trace_sequence returns a Traceologist::String — a plain string that also supports >> for writing to a file:

result = Traceologist.trace_sequence(filter: "MyClass") { MyClass.new.run }

result >> "trace.txt"       # writes to file; raises if it already exists
puts result                 # prints to stdout like any string

If the file already exists, >> raises a RuntimeError to avoid accidental overwrites.

bin/setup       # install dependencies
bundle exec rake test   # run tests
bundle exec rubocop     # lint
bin/console     # interactive prompt

Bug reports and pull requests are welcome on GitHub at https://github.com/kozy4324/traceologist.

The gem is available as open source under the terms of the MIT License.