123456789_123456789_123456789_123456789_123456789_

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

by Keiju ISHITSUKA(keiju@ishitsuka.com)

Constant Summary

  • EVENT_SYMBOL =

    Symbol table used for displaying trace information

    # File 'lib/tracer.rb', line 97
    {
      "line" => "-",
      "call" => ">",
      "return" => "<",
      "class" => "C",
      "end" => "E",
      "raise" => "^",
      "c-call" => "}",
      "c-return" => "{",
      "unknown" => "?"
    }
  • Single =

    Reference to singleton instance of Tracer

    # File 'lib/tracer.rb', line 209
    new

Class Attribute Summary

Class Method Summary

Class Attribute Details

.display_c_call? (rw)

Alias for .display_c_call.

[ GitHub ]

  
# File 'lib/tracer.rb', line 85

alias display_c_call? display_c_call

.display_process_id? (rw)

Alias for .display_process_id.

[ GitHub ]

  
# File 'lib/tracer.rb', line 77

alias display_process_id? display_process_id

.display_thread_id? (rw)

Alias for .display_thread_id.

[ GitHub ]

  
# File 'lib/tracer.rb', line 81

alias display_thread_id? display_thread_id

.stdout (rw)

output stream used to output trace (defaults to STDOUT)

[ GitHub ]

  
# File 'lib/tracer.rb', line 70

attr_accessor :stdout

.stdout_mutex (readonly)

mutex lock used by tracer for displaying trace output

[ GitHub ]

  
# File 'lib/tracer.rb', line 73

attr_reader :stdout_mutex

.verbose? (rw)

Alias for .verbose.

[ GitHub ]

  
# 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
[ GitHub ]

  
# 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)

[ GitHub ]

  
# 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)

[ GitHub ]

  
# 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)

[ GitHub ]

  
# File 'lib/tracer.rb', line 80

attr_accessor :display_thread_id

.off

Disable tracing

[ GitHub ]

  
# 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
}
[ GitHub ]

  
# File 'lib/tracer.rb', line 226

def Tracer.on
  if block_given?
    Single.on{yield}
  else
    Single.on
  end
end

.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}"
})
[ GitHub ]

  
# 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)

[ GitHub ]

  
# File 'lib/tracer.rb', line 66

attr_accessor :verbose