class Tracer
Outputs a source level execution trace of a Ruby program.
It does this by registering an event handler with Kernel#set_trace_func
for processing incoming events. It also provides methods for filtering unwanted trace output (see Tracer.add_filter
, Tracer.on
, and Tracer.off
).
Example¶ ↑
Consider the following Ruby script
class A def square(a) return a*a end end a = A.new a.square(5)
Running the above script using ruby -r tracer example.rb
will output the following trace to STDOUT (Note you can also explicitly require 'tracer'
)
#0:<internal:lib/rubygems/custom_require>:38:Kernel:<: - #0:example.rb:3::-: class A #0:example.rb:3::C: class A #0:example.rb:4::-: def square(a) #0:example.rb:7::E: end #0:example.rb:9::-: a = A.new #0:example.rb:10::-: a.square(5) #0:example.rb:4:A:>: def square(a) #0:example.rb:5:A:-: return a*a #0:example.rb:6:A:<: end | | | | | | | | | ---------------------+ event | | | ------------------------+ class | | --------------------------+ line | ------------------------------------+ filename ---------------------------------------+ thread
Symbol
table used for displaying incoming events:
- +}+
-
call a C-language routine
- +{+
-
return from a C-language routine
- +>+
-
call a Ruby method
C
-
start a class or module definition
E
-
finish a class or module definition
-
-
execute code on a new line
- +^+
-
raise an exception
- +<+
-
return from a Ruby method
Copyright¶ ↑
by Keiju ISHITSUKA(keiju@ishitsuka.com)
Constants
Attributes
display C-routine calls in trace output (defaults to false)
display C-routine calls in trace output (defaults to false)
display process id in trace output (defaults to false)
display process id in trace output (defaults to false)
display thread id in trace output (defaults to true)
display thread id in trace output (defaults to true)
output stream used to output trace (defaults to STDOUT)
mutex lock used by tracer for displaying trace output
display additional debug information (defaults to false)
display additional debug information (defaults to false)
Public Class Methods
Used to filter unwanted trace output
Example which only outputs lines of code executed within the Kernel
class:
Tracer.add_filter do |event, file, line, id, binding, klass, *rest| "Kernel" == klass.to_s end
# File lib/tracer.rb, line 268 def Tracer.add_filter(p = nil, &b) p ||= b Single.add_filter(p) end
Disable tracing
# File lib/tracer.rb, line 240 def Tracer.off Single.off end
Register an event handler p
which is called every time a line in file_name
is executed.
Example:
Tracer.set_get_line_procs("example.rb", lambda { |line| puts "line number executed is #{line}" })
# File lib/tracer.rb, line 254 def Tracer.set_get_line_procs(file_name, p = nil, &b) p ||= b Single.set_get_line_procs(file_name, p) end