class TracePoint

Document-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

:fiber_switch

event hook at fiber switch

:script_compiled

new Ruby code compiled (with eval, load or require)

Public Class Methods

new(*events) { |obj| block } → obj click to toggle source

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 ruby_3_0_5/trace_point.rb, line 95
def self.new(*events)
  Primitive.tracepoint_new_s(events)
end
stat → obj click to toggle source

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 ruby_3_0_5/trace_point.rb, line 117
def self.stat
  Primitive.tracepoint_stat_s
end
trace(*events) { |obj| block } → obj click to toggle source

Document-method: trace

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 ruby_3_0_5/trace_point.rb, line 134
def self.trace(*events)
  Primitive.tracepoint_trace_s(events)
end

Public Instance Methods

binding() click to toggle source

Return the generated binding object from event

# File ruby_3_0_5/trace_point.rb, line 313
def binding
  Primitive.tracepoint_attr_binding
end
callee_id() click to toggle source

Return the called name of the method being called

# File ruby_3_0_5/trace_point.rb, line 272
def callee_id
  Primitive.tracepoint_attr_callee_id
end
defined_class() click to toggle source

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 ruby_3_0_5/trace_point.rb, line 308
def defined_class
  Primitive.tracepoint_attr_defined_class
end
disable → true or false click to toggle source
disable { block } → obj

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 ruby_3_0_5/trace_point.rb, line 231
def disable
  Primitive.tracepoint_disable_m
end
enable(target: nil, target_line: nil, target_thread: nil) → true or false click to toggle source
enable(target: nil, target_line: nil, target_thread: nil) { block } → obj

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 ruby_3_0_5/trace_point.rb, line 195
def enable(target: nil, target_line: nil, target_thread: nil)
  Primitive.tracepoint_enable_m(target, target_line, target_thread)
end
enabled? → true or false click to toggle source

The current status of the trace

# File ruby_3_0_5/trace_point.rb, line 239
def enabled?
  Primitive.tracepoint_enabled_p
end
eval_script() click to toggle source

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

# File ruby_3_0_5/trace_point.rb, line 337
def eval_script
  Primitive.tracepoint_attr_eval_script
end
event() click to toggle source

Type of event

See Events at TracePoint for more information.

# File ruby_3_0_5/trace_point.rb, line 246
def event
  Primitive.tracepoint_attr_event
end
inspect → string click to toggle source

Return a string containing a human-readable TracePoint status.

# File ruby_3_0_5/trace_point.rb, line 104
def inspect
  Primitive.tracepoint_inspect
end
instruction_sequence() click to toggle source

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

Note that this method is MRI specific.

# File ruby_3_0_5/trace_point.rb, line 345
def instruction_sequence
  Primitive.tracepoint_attr_instruction_sequence
end
lineno() click to toggle source

Line number of the event

# File ruby_3_0_5/trace_point.rb, line 251
def lineno
  Primitive.tracepoint_attr_lineno
end
method_id() click to toggle source

Return the name at the definition of the method being called

# File ruby_3_0_5/trace_point.rb, line 267
def method_id
  Primitive.tracepoint_attr_method_id
end
parameters() click to toggle source

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

# File ruby_3_0_5/trace_point.rb, line 262
def parameters
  Primitive.tracepoint_attr_parameters
end
path() click to toggle source

Path of the file being run

# File ruby_3_0_5/trace_point.rb, line 256
def path
  Primitive.tracepoint_attr_path
end
raised_exception() click to toggle source

Value from exception raised on the :raise event

# File ruby_3_0_5/trace_point.rb, line 331
def raised_exception
  Primitive.tracepoint_attr_raised_exception
end
return_value() click to toggle source

Return value from :return, c_return, and b_return event

# File ruby_3_0_5/trace_point.rb, line 326
def return_value
  Primitive.tracepoint_attr_return_value
end
self() click to toggle source

Return the trace object during event

Same as TracePoint#binding:

trace.binding.eval('self')
# File ruby_3_0_5/trace_point.rb, line 321
def self
  Primitive.tracepoint_attr_self
end