TracePoint
<img src=“http://travis-ci.org/rubyworks/tracepoint.png” />
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)
Copyright © 2005,2010 Rubyworks, Thomas Sawyer
TracePoint is distributable in accordance with the terms of the FreeBSD license.
See COPYING.rdoc for details.