TracePoint

Home | Code | Mail

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

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.