class TracePoint
A class that provides the functionality of Kernel#set_trace_func in a nice Object-Oriented API.
Example¶ ↑
We can use TracePoint to gather information specifically for exceptions:
trace = TracePoint.new(:raise) do |tp| p [tp.lineno, tp.event, tp.raised_exception] end #=> #<TracePoint:disabled> trace.enable #=> false 0 / 0 #=> [5, :raise, #<ZeroDivisionError: divided by 0>]
Events¶ ↑
If you don't specify the type of events you want to listen for, TracePoint will include all available events.
Note do not depend on current event set, as this list is subject to change. Instead, it is recommended you specify the type of events you want to use.
To filter what is traced, you can pass any of the following as
events
:
:line
-
execute code on a new line
:class
-
start a class or module definition
:end
-
finish a class or module definition
:call
-
call a Ruby method
:return
-
return from a Ruby method
:c_call
-
call a C-language routine
:c_return
-
return from a C-language routine
:raise
-
raise an exception
:b_call
-
event hook at block entry
:b_return
-
event hook at block ending
:thread_begin
-
event hook at thread beginning
:thread_end
-
event hook at thread ending
Public Class Methods
Returns a new TracePoint object, not enabled by default.
Next, in order to activate the trace, you must use #enable
trace = TracePoint.new(:call) do |tp| p [tp.lineno, tp.defined_class, tp.method_id, tp.event] end #=> #<TracePoint:disabled> trace.enable #=> false puts "Hello, TracePoint!" # ... # [48, IRB::Notifier::AbstractNotifier, :printf, :call] # ...
When you want to deactivate the trace, you must use #disable
trace.disable
See Events at TracePoint for possible events and more information.
A block must be given, otherwise a ThreadError is raised.
If the trace method isn't included in the given events filter, a RuntimeError is raised.
TracePoint.trace(:line) do |tp| p tp.raised_exception end #=> RuntimeError: 'raised_exception' not supported by this event
If the trace method is called outside block, a RuntimeError is raised.
TracePoint.trace(:line) do |tp| $tp = tp end $tp.line #=> access from outside (RuntimeError)
Access from other threads is also forbidden.
static VALUE tracepoint_new_s(int argc, VALUE *argv, VALUE self) { rb_event_flag_t events = 0; int i; if (argc > 0) { for (i=0; i<argc; i++) { events |= symbol2event_flag(argv[i]); } } else { events = RUBY_EVENT_TRACEPOINT_ALL; } if (!rb_block_given_p()) { rb_raise(rb_eThreadError, "must be called with a block"); } return tracepoint_new(self, 0, events, 0, 0, rb_block_proc()); }
A convenience method for ::new, that activates the trace automatically.
trace = TracePoint.trace(:call) { |tp| [tp.lineno, tp.event] } #=> #<TracePoint:enabled> trace.enabled? #=> true
static VALUE tracepoint_trace_s(int argc, VALUE *argv, VALUE self) { VALUE trace = tracepoint_new_s(argc, argv, self); rb_tracepoint_enable(trace); return trace; }
Public Instance Methods
Return the generated binding object from event
static VALUE tracepoint_attr_binding(VALUE tpval) { return rb_tracearg_binding(get_trace_arg()); }
Return class or module of the method being called.
class C; def foo; end; end trace = TracePoint.new(:call) do |tp| p tp.defined_class #=> C end.enable do C.new.foo end
If method is defined by a module, then that module is returned.
module M; def foo; end; end class C; include M; end; trace = TracePoint.new(:call) do |tp| p tp.defined_class #=> M end.enable do C.new.foo end
Note: defined_class returns singleton class.
6th block parameter of Kernel#set_trace_func passes original class of attached by singleton class.
This is a difference between Kernel#set_trace_func and TracePoint.
class C; def self.foo; end; end trace = TracePoint.new(:call) do |tp| p tp.defined_class #=> #<Class:C> end.enable do C.foo end
static VALUE tracepoint_attr_defined_class(VALUE tpval) { return rb_tracearg_defined_class(get_trace_arg()); }
Deactivates the trace
Return true if trace was enabled. Return false if trace was disabled.
trace.enabled? #=> true trace.disable #=> false (previous status) trace.enabled? #=> false trace.disable #=> false
If a block is given, the trace will only be disable within the scope of the block.
trace.enabled? #=> true trace.disable do trace.enabled? # only disabled for this block end trace.enabled? #=> true
Note: You cannot access event hooks within the block.
trace.disable { p tp.lineno } #=> RuntimeError: access from outside
static VALUE tracepoint_disable_m(VALUE tpval) { rb_tp_t *tp = tpptr(tpval); int previous_tracing = tp->tracing; rb_tracepoint_disable(tpval); if (rb_block_given_p()) { return rb_ensure(rb_yield, Qnil, previous_tracing ? rb_tracepoint_enable : rb_tracepoint_disable, tpval); } else { return previous_tracing ? Qtrue : Qfalse; } }
Activates the trace
Return true if trace was enabled. Return false if trace was disabled.
trace.enabled? #=> false trace.enable #=> false (previous state) # trace is enabled trace.enabled? #=> true trace.enable #=> true (previous state) # trace is still enabled
If a block is given, the trace will only be enabled within the scope of the block.
trace.enabled? #=> false trace.enable do trace.enabled? # only enabled for this block end trace.enabled? #=> false
Note: You cannot access event hooks within the block.
trace.enable { p tp.lineno } #=> RuntimeError: access from outside
static VALUE tracepoint_enable_m(VALUE tpval) { rb_tp_t *tp = tpptr(tpval); int previous_tracing = tp->tracing; rb_tracepoint_enable(tpval); if (rb_block_given_p()) { return rb_ensure(rb_yield, Qnil, previous_tracing ? rb_tracepoint_enable : rb_tracepoint_disable, tpval); } else { return previous_tracing ? Qtrue : Qfalse; } }
The current status of the trace
VALUE rb_tracepoint_enabled_p(VALUE tpval) { rb_tp_t *tp = tpptr(tpval); return tp->tracing ? Qtrue : Qfalse; }
Type of event
See Events at TracePoint for more information.
static VALUE tracepoint_attr_event(VALUE tpval) { return rb_tracearg_event(get_trace_arg()); }
Return a string containing a human-readable TracePoint status.
static VALUE tracepoint_inspect(VALUE self) { rb_tp_t *tp = tpptr(self); rb_trace_arg_t *trace_arg = GET_THREAD()->trace_arg; if (trace_arg) { switch (trace_arg->event) { case RUBY_EVENT_LINE: case RUBY_EVENT_SPECIFIED_LINE: { VALUE sym = rb_tracearg_method_id(trace_arg); if (NIL_P(sym)) goto default_inspect; return rb_sprintf("#<TracePoint:%"PRIsVALUE"@%"PRIsVALUE":%d in `%"PRIsVALUE"'>", rb_tracearg_event(trace_arg), rb_tracearg_path(trace_arg), FIX2INT(rb_tracearg_lineno(trace_arg)), sym); } case RUBY_EVENT_CALL: case RUBY_EVENT_C_CALL: case RUBY_EVENT_RETURN: case RUBY_EVENT_C_RETURN: return rb_sprintf("#<TracePoint:%"PRIsVALUE" `%"PRIsVALUE"'@%"PRIsVALUE":%d>", rb_tracearg_event(trace_arg), rb_tracearg_method_id(trace_arg), rb_tracearg_path(trace_arg), FIX2INT(rb_tracearg_lineno(trace_arg))); case RUBY_EVENT_THREAD_BEGIN: case RUBY_EVENT_THREAD_END: return rb_sprintf("#<TracePoint:%"PRIsVALUE" %"PRIsVALUE">", rb_tracearg_event(trace_arg), rb_tracearg_self(trace_arg)); default: default_inspect: return rb_sprintf("#<TracePoint:%"PRIsVALUE"@%"PRIsVALUE":%d>", rb_tracearg_event(trace_arg), rb_tracearg_path(trace_arg), FIX2INT(rb_tracearg_lineno(trace_arg))); } } else { return rb_sprintf("#<TracePoint:%s>", tp->tracing ? "enabled" : "disabled"); } }
Line number of the event
static VALUE tracepoint_attr_lineno(VALUE tpval) { return rb_tracearg_lineno(get_trace_arg()); }
Return the name of the method being called
static VALUE tracepoint_attr_method_id(VALUE tpval) { return rb_tracearg_method_id(get_trace_arg()); }
Path of the file being run
static VALUE tracepoint_attr_path(VALUE tpval) { return rb_tracearg_path(get_trace_arg()); }
Value from exception raised on the :raise
event
static VALUE tracepoint_attr_raised_exception(VALUE tpval) { return rb_tracearg_raised_exception(get_trace_arg()); }
Return value from :return
, c_return
, and
b_return
event
static VALUE tracepoint_attr_return_value(VALUE tpval) { return rb_tracearg_return_value(get_trace_arg()); }
Return the trace object during event
Same as #binding:
trace.binding.eval('self')
static VALUE tracepoint_attr_self(VALUE tpval) { return rb_tracearg_self(get_trace_arg()); }