TracePoint

In general, while a TracePoint callback is running, other registered callbacks are not called to avoid confusion by reentrance. This method allows the reentrance in a given block. This method should be used carefully, otherwise the callback can be easily called infinitely.

If this method is called when the reentrance is already allowed, it raises a RuntimeError.

 
               # File trace_point.rb, line 150
def self.allow_reentry
  Primitive.tracepoint_allow_reentry
end
            

Returns a new TracePoint object, not enabled by default.

Next, in order to activate the trace, you must use TracePoint#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 TracePoint#disable

trace.disable

See Events at TracePoint for possible events and more information.

A block must be given, otherwise an ArgumentError 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.lineno #=> access from outside (RuntimeError)

Access from other threads is also forbidden.

 
               # File trace_point.rb, line 97
def self.new(*events)
  Primitive.tracepoint_new_s(events)
end
            

Returns internal information of TracePoint.

The contents of the returned value are implementation specific. It may be changed in future.

This method is only for debugging TracePoint itself.

 
               # File trace_point.rb, line 119
def self.stat
  Primitive.tracepoint_stat_s
end
            

A convenience method for TracePoint.new, that activates the trace automatically.

trace = TracePoint.trace(:call) { |tp| [tp.lineno, tp.event] }
#=> #<TracePoint:enabled>

trace.enabled? #=> true

 
               # File trace_point.rb, line 134
def self.trace(*events)
  Primitive.tracepoint_trace_s(events)
end
            

Return the generated binding object from event.

Note that for c_call and c_return events, the binding returned is the binding of the nearest Ruby method calling the C method, since C methods themselves do not have bindings.

 
               # File trace_point.rb, line 333
def binding
  Primitive.tracepoint_attr_binding
end
            

Return the called name of the method being called

 
               # File trace_point.rb, line 288
def callee_id
  Primitive.tracepoint_attr_callee_id
end
            

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

 
               # File trace_point.rb, line 324
def defined_class
  Primitive.tracepoint_attr_defined_class
end
            

Deactivates the trace

Return true if trace was enabled. Return false if trace was disabled.

trace.enabled?      #=> true
trace.disable       #=> true (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

 
               # File trace_point.rb, line 247
def disable
  Primitive.tracepoint_disable_m
end
            

Activates the trace.

Returns true if trace was enabled. Returns 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

target, target_line and target_thread parameters are used to limit tracing only to specified code objects. target should be a code object for which RubyVM::InstructionSequence.of will return an instruction sequence.

t = TracePoint.new(:line) { |tp| p tp }

def m1
  p 1
end

def m2
  p 2
end

t.enable(target: method(:m1))

m1
# prints #<TracePoint:line test.rb:4 in `m1'>
m2
# prints nothing

Note: You cannot access event hooks within the enable block.

trace.enable { p tp.lineno }
#=> RuntimeError: access from outside

 
               # File trace_point.rb, line 211
def enable(target: nil, target_line: nil, target_thread: nil)
  Primitive.tracepoint_enable_m(target, target_line, target_thread)
end
            

The current status of the trace

 
               # File trace_point.rb, line 255
def enabled?
  Primitive.tracepoint_enabled_p
end
            

Compiled source code (String) on *eval methods on the :script_compiled event. If loaded from a file, it will return nil.

 
               # File trace_point.rb, line 359
def eval_script
  Primitive.tracepoint_attr_eval_script
end
            

Type of event

See Events at TracePoint for more information.

 
               # File trace_point.rb, line 262
def event
  Primitive.tracepoint_attr_event
end
            

Return a string containing a human-readable TracePoint status.

 
               # File trace_point.rb, line 106
def inspect
  Primitive.tracepoint_inspect
end
            

Compiled instruction sequence represented by a RubyVM::InstructionSequence instance on the :script_compiled event.

Note that this method is MRI specific.

 
               # File trace_point.rb, line 367
def instruction_sequence
  Primitive.tracepoint_attr_instruction_sequence
end
            

Line number of the event

 
               # File trace_point.rb, line 267
def lineno
  Primitive.tracepoint_attr_lineno
end
            

Return the name at the definition of the method being called

 
               # File trace_point.rb, line 283
def method_id
  Primitive.tracepoint_attr_method_id
end
            

Return the parameters definition of the method or block that the current hook belongs to. Format is the same as for Method#parameters

 
               # File trace_point.rb, line 278
def parameters
  Primitive.tracepoint_attr_parameters
end
            

Path of the file being run

 
               # File trace_point.rb, line 272
def path
  Primitive.tracepoint_attr_path
end
            

Value from exception raised on the :raise event

 
               # File trace_point.rb, line 353
def raised_exception
  Primitive.tracepoint_attr_raised_exception
end
            

Return value from :return, c_return, and b_return event

 
               # File trace_point.rb, line 348
def return_value
  Primitive.tracepoint_attr_return_value
end
            

Return the trace object during event

Same as the following, except it returns the correct object (the method receiver) for c_call and c_return events:

trace.binding.eval('self')

 
               # File trace_point.rb, line 343
def self
  Primitive.tracepoint_attr_self
end