class Tracer - RDoc Documentation

# 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

EVENT_SYMBOL

  `Symbol` table used for displaying trace information

Single

  Reference to singleton instance of `Tracer`

VERSION
display_c_call
display_process_id
display_thread_id
stdout
verbose

### Attributes

display_c_call[RW]

display C-routine calls in trace output (defaults to false)

display_c_call?[RW]

display C-routine calls in trace output (defaults to false)

display_process_id[RW]

display process id in trace output (defaults to false)

display_process_id?[RW]

display process id in trace output (defaults to false)

display_thread_id[RW]

display thread id in trace output (defaults to true)

display_thread_id?[RW]

display thread id in trace output (defaults to true)

stdout[RW]

output stream used to output trace (defaults to STDOUT)

stdout_mutex[R]

mutex lock used by tracer for displaying trace output

verbose[RW]

display additional debug information (defaults to false)

verbose?[RW]

display additional debug information (defaults to false)

### Public Class Methods

add_filter(p = nil, &b) click to toggle source

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

off() click to toggle source

Disable tracing

    # File lib/tracer.rb, line 240
    def Tracer.off
      Single.off
    end

on() { || ... } click to toggle source

Start tracing

### Example¶ ↑

    Tracer.on
    # code to trace here
    Tracer.off

You can also pass a block:

    Tracer.on {
      # trace everything in this block
    }

    # File lib/tracer.rb, line 229
    def Tracer.on
      if block_given?
        Single.on{yield}
      else
        Single.on
      end
    end

set_get_line_procs(file_name, p = nil, &b) click to toggle source

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