Class: Tracer
Relationships & Source Files | |
Inherits: | Object |
Defined in: | lib/tracer.rb |
Overview
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 .add_filter, .on, and .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)
Constant Summary
-
EVENT_SYMBOL =
Symbol table used for displaying trace information
{ "line" => "-", "call" => ">", "return" => "<", "class" => "C", "end" => "E", "raise" => "^", "c-call" => "}", "c-return" => "{", "unknown" => "?" }
-
Single =
Reference to singleton instance of
Tracer
new
Class Attribute Summary
-
.display_c_call?
rw
Alias for .display_c_call.
-
.display_process_id?
rw
Alias for .display_process_id.
-
.display_thread_id?
rw
Alias for .display_thread_id.
-
.stdout
rw
output stream used to output trace (defaults to STDOUT).
-
.verbose?
rw
Alias for .verbose.
-
.stdout_mutex
readonly
mutex lock used by tracer for displaying trace output.
Class Method Summary
-
.add_filter(p = proc)
Used to filter unwanted trace output.
-
.display_c_call
(also: .display_c_call?)
rw
display C-routine calls in trace output (defaults to false).
-
.display_process_id
(also: .display_process_id?)
rw
display process id in trace output (defaults to false).
-
.display_thread_id
(also: .display_thread_id?)
rw
display thread id in trace output (defaults to true).
-
.off
Disable tracing.
-
.on
Start tracing.
-
.set_get_line_procs(file_name, p = proc)
Register an event handler
p
which is called everytime a line infile_name
is executed. -
.verbose
(also: .verbose?)
rw
display additional debug information (defaults to false).
Class Attribute Details
.display_c_call? (rw)
Alias for .display_c_call.
# File 'lib/tracer.rb', line 85
alias display_c_call? display_c_call
.display_process_id? (rw)
Alias for .display_process_id.
# File 'lib/tracer.rb', line 77
alias display_process_id? display_process_id
.display_thread_id? (rw)
Alias for .display_thread_id.
# File 'lib/tracer.rb', line 81
alias display_thread_id? display_thread_id
.stdout (rw)
output stream used to output trace (defaults to STDOUT)
# File 'lib/tracer.rb', line 70
attr_accessor :stdout
.stdout_mutex (readonly)
mutex lock used by tracer for displaying trace output
# File 'lib/tracer.rb', line 73
attr_reader :stdout_mutex
.verbose? (rw)
Alias for .verbose.
# File 'lib/tracer.rb', line 67
alias verbose? verbose
Class Method Details
.add_filter(p = proc)
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 264
def Tracer.add_filter(p = proc) Single.add_filter(p) end
.display_c_call (rw) Also known as: .display_c_call?
display C-routine calls in trace output (defaults to false)
# File 'lib/tracer.rb', line 84
attr_accessor :display_c_call
.display_process_id (rw) Also known as: .display_process_id?
display process id in trace output (defaults to false)
# File 'lib/tracer.rb', line 76
attr_accessor :display_process_id
.display_thread_id (rw) Also known as: .display_thread_id?
display thread id in trace output (defaults to true)
# File 'lib/tracer.rb', line 80
attr_accessor :display_thread_id
.off
Disable tracing
# File 'lib/tracer.rb', line 237
def Tracer.off Single.off end
.on
Start tracing
Example
Tracer.on
# code to trace here
Tracer.off
You can also pass a block:
Tracer.on {
# trace everything in this block
}
.set_get_line_procs(file_name, p = proc)
Register an event handler p
which is called everytime 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 251
def Tracer.set_get_line_procs(file_name, p = proc) Single.set_get_line_procs(file_name, p) end
.verbose (rw) Also known as: .verbose?
display additional debug information (defaults to false)
# File 'lib/tracer.rb', line 66
attr_accessor :verbose