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 96 
    {
  "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 208 
    new

Class Attribute Summary

Class Method Summary

Instance Method Summary

Constructor Details

.new ⇒ Tracer

This method is for internal use only.
[ GitHub ] 

  


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



def initialize # :nodoc:
  @threads = Hash.new
  if defined? Thread.main
    @threads[Thread.main.object_id] = 0
  else
    @threads[Thread.current.object_id] = 0
  end

  @get_line_procs = {}

  @filters = []
end


  







Class Attribute Details



  

    .display_c_call?   (rw)
  



  

    

Alias for .display_c_call.


  



  [ GitHub ]


  

  


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



alias display_c_call? display_c_call


  








  

    .display_process_id?   (rw)
  



  

    

Alias for .display_process_id.


  



  [ GitHub ]


  

  


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



alias display_process_id? display_process_id


  








  

    .display_thread_id?   (rw)
  



  

    

Alias for .display_thread_id.


  



  [ GitHub ]


  

  


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



alias display_thread_id? display_thread_id


  








  

    .stdout   (rw)
  



  

    

output stream used to output trace (defaults to STDOUT)


  



  [ GitHub ]


  

  


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



attr_accessor :stdout


  








  

    .stdout_mutex   (readonly)
  



  

    

mutex lock used by tracer for displaying trace output


  



  [ GitHub ]


  

  


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



attr_reader :stdout_mutex


  








  

    .verbose?   (rw)
  



  

    

Alias for .verbose.


  



  [ GitHub ]


  

  


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



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 263



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 83



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 75



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 79



attr_accessor :display_thread_id


  








  

    .off  
  



  

    

Disable tracing


  



  [ GitHub ]


  

  


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



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 225



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 250



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 65



attr_accessor :verbose


  







Instance Method Details



  

    #add_filter(p = proc)  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


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



def add_filter(p = proc) # :nodoc:
  @filters.push p
end


  








  

    #get_line(file, line)  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


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



def get_line(file, line) # :nodoc:
  if p = @get_line_procs[file]
    return p.call(line)
  end

  unless list = SCRIPT_LINES__[file]
    list = File.readlines(file) rescue []
    SCRIPT_LINES__[file] = list
  end

  if l = list[line - 1]
    l
  else
    "-\n"
  end
end


  








  

    #get_thread_no  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


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



def get_thread_no # :nodoc:
  if no = @threads[Thread.current.object_id]
    no
  else
    @threads[Thread.current.object_id] = @threads.size
  end
end


  








  

    #off  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


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



def off # :nodoc:
  set_trace_func nil
  stdout.print "Trace off\n" if Tracer.verbose?
end


  








  

    #on  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


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



def on # :nodoc:
  if block_given?
    on
    begin
      yield
    ensure
      off
    end
  else
    set_trace_func method(:trace_func).to_proc
    stdout.print "Trace on\n" if Tracer.verbose?
  end
end


  








  

    #set_get_line_procs(file, p = proc)  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


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



def set_get_line_procs(file, p = proc) # :nodoc:
  @get_line_procs[file] = p
end


  








  

    #stdout  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


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



def stdout # :nodoc:
  Tracer.stdout
end


  








  

    #trace_func(event, file, line, id, binding, klass)  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


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



def trace_func(event, file, line, id, binding, klass, *) # :nodoc:
  return if file == __FILE__

  for p in @filters
    return unless p.call event, file, line, id, binding, klass
  end

  return unless Tracer::display_c_call? or
    event != "c-call" && event != "c-return"

  Tracer::stdout_mutex.synchronize do
    if EVENT_SYMBOL[event]
      stdout.printf("<%d>", $$) if Tracer::display_process_id?
      stdout.printf("#%d:", get_thread_no) if Tracer::display_thread_id?
      if line == 0
        source = "?\n"
      else
        source = get_line(file, line)
      end
      stdout.printf("%s:%d:%s:%s: %s",
             file,
             line,
             klass || '',
             EVENT_SYMBOL[event],
             source)
    end
  end

end