Skip to content
Tutorials Center
My learning

Topics

Lesson 110 of 134 ยท Testing and Tooling

TracePoint and Profiling

Learn Ruby's TracePoint to watch method calls, returns, raises and line events, build a call counter and tracer, write a toy sampling profiler, and use stackprof.

Sometimes puts debugging is not enough. You want to know every method a request called, in which order, how often, and which exception was raised where. Ruby has a built-in instrument for this: TracePoint. It lets you subscribe to events inside the running interpreter (a method call, a return, a raised exception, a new line of code) and run a block each time one happens.

TracePoint is how debuggers, coverage tools and some profilers are built. It is exact but slow, since it hooks every event. For finding the hot spot of a real program you instead use a sampling profiler, which looks at the call stack a hundred times a second. This lesson covers both, so you can choose the right instrument.

Your first TracePoint

You create a TracePoint with the events you care about, then enable it, either around a block or with enable/disable. Inside the block you receive the trace point tp, which describes the event: tp.event, tp.method_id, tp.defined_class, tp.lineno, tp.path, tp.return_value and more.

Ruby Tracing method calls and returns

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

trace.enable { ... } turns the trace on only while the block runs and returns the block's value. Outside the block the trace is off, so nothing outside is slowed down. Only Ruby-defined methods fire :call and :return; methods written in C (such as Integer#+) fire :c_call and :c_return.

sequenceDiagram
  participant P as Your code
  participant R as Ruby VM
  participant T as TracePoint block
  P->>R: sum_of_squares(3, 4)
  R->>T: event :call
  R->>R: run method body
  R->>T: event :return
  R-->>P: result

The VM calls your trace block before and after a method body; your block runs inside the program, so keep it small.

The events you can subscribe to

Event When it fires
:call / :return A Ruby method starts / finishes
:c_call / :c_return A method written in C starts / finishes
:b_call / :b_return A block starts / finishes
:line A new line of code is about to run
:raise An exception is raised
:rescue An exception is rescued
:class / :end A class or module body opens / closes
:thread_begin / :thread_end A thread starts / ends

Passing no event names subscribes to the common ones. Choose only what you need: :line generates an event for every line executed and is by far the most expensive.

Counting calls: a simple profiler

Because TracePoint sees every call, you can count how many times each method runs. Call counts are deterministic, which makes them a good teaching tool and a good test of an algorithm's cost.

Ruby Call counts for naive and memoized Fibonacci

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The naive version makes 1,973 calls for n = 15 and 21,891 for n = 20: the work grows exponentially. The memoized version stays linear. No clock is involved, so the numbers are identical on every machine. See Recursion for why.

Tracing exceptions and arguments

A :raise event gives you tp.raised_exception. That is handy for finding where an exception originates, even when something far up the stack rescues it silently. For :call events you can read the arguments through the trace point's binding.

Ruby Who raised what, and with which arguments

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

The silent rescue hid the failure from the caller, but TracePoint still saw it. Notice that the exception is reported "in Integer": Kernel#Integer is itself a Ruby-defined method in current Rubies, so it shows up as a :call too. tp.parameters lists the parameter names (like Method#parameters, see Reflection) and tp.binding lets you read their values. Using tp.binding is convenient for debugging tools; do not use it in hot paths.

Narrowing the trace

Tracing everything also traces your own tracing code and every library. Two options keep it focused:

  • target: limits a trace point to one method, proc or block: trace.enable(target: method(:parse_age)).
  • target_thread: limits it to one thread, which is the default when you use the block form of enable.
Ruby Tracing only one method

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

main was called too, but only helper was in the target, so only helper shows up. With target: Ruby instruments just that code, so the overhead of the rest of the program is gone.

A toy sampling profiler

TracePoint's cost is the reason a production profiler does not use it. A sampling profiler instead wakes up on a timer, records backtrace of the running thread and moves on. Methods that appear in many samples are where the time goes. Timing varies per run, so the example below prints only structure and never exact counts.

Ruby Sampling the main thread

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

That is the whole idea of a sampling profiler: no hooks on the profiled code, a small constant overhead, and a statistical answer ("about 90% of samples were in hot_method"). The cost is accuracy for very short functions. Real tools do this in C with much better precision and call stacks, and can sample by CPU time instead of wall time.

Real profiling tools

These are third-party gems, so the snippets are read-only:

Terminal
# read-only example: stackprof is a sampling profiler written as a C extension
gem install stackprof
stackprof run --mode=cpu --out tmp/stackprof.dump -- ruby script.rb
stackprof tmp/stackprof.dump --text --limit 10
Ruby
# read-only example: profile a block from inside Ruby
require 'stackprof'

StackProf.run(mode: :cpu, out: 'tmp/stackprof-cpu.dump', interval: 1000) do
  expensive_work
end
  • stackprof samples CPU, wall or object-allocation events and can produce flamegraphs.
  • ruby-prof traces every call (like our TracePoint counter) and gives exact call graphs, at a large slowdown.
  • memory_profiler and ObjectSpace.trace_object_allocations find which lines allocate objects (see ObjectSpace, WeakRef and the Garbage Collector).
  • rbspy samples a running Ruby process from the outside without changing it.

A good workflow: sample first to find the hot method, then use a precise tool (or TracePoint with target:) on just that part, then confirm the fix with a benchmark (Benchmarking).

Cautions

  • A TracePoint block runs inside the program: raising an exception in it breaks the traced code, and tracing slows execution a lot.
  • Never leave TracePoints enabled in production; enable them around the code you study.
  • Events fired by the trace block itself are ignored by default while it runs, so you cannot trace the tracer.
  • Behavior of events such as :line for multi-line expressions can change between Ruby versions; do not build tests on exact line numbers of internals.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which TracePoint events fire when a Ruby-defined method starts and finishes?

    :call and :return are for methods written in Ruby. :c_call and :c_return are for methods implemented in C.
  2. 2. How do you make a TracePoint fire only for one method?

    enable(target: ...) instruments only that method, proc or block, which also removes the overhead for the rest of the program.
  3. 3. What is the main advantage of a sampling profiler over a TracePoint-based one?

    Sampling does not hook every event, so it is cheap enough for real workloads. The trade-off is that results are statistical.
  4. 4. What does tp.raised_exception give you?

    On a :raise event the TracePoint exposes the exception object, so you can see where it was created even when a distant rescue hides it.

Summary

  • TracePoint.new(:call, :return) { |tp| ... } subscribes to interpreter events; enable it around a block with trace.enable { ... }.
  • Events include calls, returns, C calls, blocks, lines, raises, rescues and class bodies; tp exposes method_id, return_value, raised_exception, parameters and binding.
  • Use target: to limit the trace and keep the overhead small.
  • Call counts from a TracePoint are exact and deterministic, which is perfect for comparing algorithms.
  • Sampling profilers (stackprof, rbspy) find the hot spot in real programs; precise tracers are for a small area afterward.

Next: Rails Overview