TracePoint

Description

TracePoint is a Binding with the addition of event information. In theory it would function very well as the join-point for AOP. In practice it provides a better approach to #set_trace_func.

IMPOTRANT! TracePoint does not fully work under Ruby 1.9.0-1.9.3, not because there is anything wrong with TracePoint, but because Ruby 1.9 has a bug in ‘#set_trace_func` in which the binding parameter is incorrect.

Features

More versatile than #set_trace_func.
Easy to set multiple traces.
Can activate and deactivate traces on the fly.

Synopsis

Using TracePoint is simply a matter of setting the #trace procedure. For example to watch everything that happens during a Ruby process:

TracePoint.trace do |tp|
  puts "#{tp.self.class}\t#{tp.callee}\t#{tp.event}\t#{tp.return?}"
end

TracePoint.activate

1 + 1

Produces:

Object       line       false
Fixnum   +   c-call     false
Fixnum   +   c-return   false

Tracing can be deactivated and reactivated on the fly by calling #deactivate and #activate.

To add additional trace procedures, simply call the #trace method again. Trace procedures can also be named by providing a name argument to the #trace method. This allows traces to be added and removed without affecting other traces.

TracePoint.trace(:class_trace) do |tp|
  puts tp.self.class
end

TracePoint.trace(:method_trace) do |tp|
  puts tp.callee
end

# ...

TracePoint.clear(:class_trace)

Calling #clear with no arguments will remove all trace procedures and deactivate tracing.

Please see the API documentation for more information.

Install

Follow the usual procedure for installing via RubyGems:

$ gem install tracepoint

Copyrights

(BSD-2-Clause License)

TracePoint is distributable in accordance with the terms of the FreeBSD license.

See COPYING.rdoc for details.