Rotoscope

Rotoscope is a high-performance logger of Ruby method invocations.

Status

Rotoscope is subject to breaking changes in minor versions until 1.0 is available.

Table of Contents

• Example
• API
  • Default Logging Interface
  • Low-level API

Example

require 'rotoscope'

class Dog
  def bark
    Noisemaker.speak('woof!')
  end
end

class Noisemaker
  def self.speak(str)
    puts(str)
  end
end

log_file = File.expand_path('dog_trace.log')
puts "Writing to #{log_file}..."

Rotoscope::CallLogger.trace(log_file) do
  dog1 = Dog.new
  dog1.bark
end

The resulting method calls are saved in the specified dest in the order they were received.

Sample output:

entity,method_name,method_level,filepath,lineno,caller_entity,caller_method_name,caller_method_level
Dog,new,class,example/dog.rb,19,<ROOT>,<UNKNOWN>,<UNKNOWN>
Dog,initialize,instance,example/dog.rb,19,Dog,new,class
Dog,bark,instance,example/dog.rb,20,<ROOT>,<UNKNOWN>,<UNKNOWN>
Noisemaker,speak,class,example/dog.rb,5,Dog,bark,instance
Noisemaker,puts,class,example/dog.rb,11,Noisemaker,speak,class
IO,puts,instance,example/dog.rb,11,Noisemaker,puts,class
IO,write,instance,example/dog.rb,11,IO,puts,instance
IO,write,instance,example/dog.rb,11,IO,puts,instance

API

Default Logging Interface

Rotoscope ships with a default logger, Rotoscope::CallLogger. This provides a simple-to-use interface to the tracing engine that maintains performance as much as possible.

• .trace
• .new
• #trace
• #start_trace
• #stop_trace
• #mark
• #close
• #state
• #closed?

Rotoscope::CallLogger.trace(dest, excludelist: [])

Writes all calls of methods to dest, except for those whose filepath contains any entry in excludelist. dest is either a filename or an IO. Methods invoked at the top of the trace will have a caller entity of <ROOT> and a caller method name of <UNKNOWN>.

Rotoscope::CallLogger.trace(dest) { |call| ... }
# or...
Rotoscope::CallLogger.trace(dest, excludelist: ["/.gem/"]) { |call| ... }

Rotoscope::CallLogger.new(dest, excludelist: [])

Same interface as Rotoscope::CallLogger::trace, but returns a Rotoscope::CallLogger instance, allowing fine-grain control via Rotoscope::CallLogger#start_trace and Rotoscope::CallLogger#stop_trace.

rs = Rotoscope::CallLogger.new(dest)
# or...
rs = Rotoscope::CallLogger.new(dest, excludelist: ["/.gem/"])

Rotoscope::CallLogger#trace(&block)

Similar to Rotoscope::CallLogger::trace, but does not need to create a file handle on invocation.

rs = Rotoscope::CallLogger.new(dest)
rs.trace do |rotoscope|
  # code to trace...
end

Rotoscope::CallLogger#start_trace

Begins writing method calls to the dest specified in the initializer.

rs = Rotoscope::CallLogger.new(dest)
rs.start_trace
# code to trace...
rs.stop_trace

Rotoscope::CallLogger#stop_trace

Stops writing method invocations to the dest. Subsequent calls to Rotoscope::CallLogger#start_trace may be invoked to resume tracing.

rs = Rotoscope::CallLogger.new(dest)
rs.start_trace
# code to trace...
rs.stop_trace

Rotoscope::CallLogger#mark(str = "")

Inserts a marker '--- ' to divide output. Useful for segmenting multiple blocks of code that are being profiled. If str is provided, the line will be prefixed by '--- ', followed by the string passed.

rs = Rotoscope::CallLogger.new(dest)
rs.start_trace
# code to trace...
rs.mark('Something goes wrong here') # produces `--- Something goes wrong here` in the output
# more code ...
rs.stop_trace

Rotoscope::CallLogger#close

Flushes the buffer and closes the file handle. Once this is invoked, no more writes can be performed on the Rotoscope::CallLogger object. Sets state to :closed.

rs = Rotoscope::CallLogger.new(dest)
rs.trace { |rotoscope| ... }
rs.close

Rotoscope::CallLogger#state

Returns the current state of the Rotoscope::CallLogger object. Valid values are :open, :tracing and :closed.

rs = Rotoscope::CallLogger.new(dest)
rs.state # :open
rs.trace do
  rs.state # :tracing
end
rs.close
rs.state # :closed

Rotoscope::CallLogger#closed?

Shorthand to check if the state is set to :closed.

rs = Rotoscope::CallLogger.new(dest)
rs.closed? # false
rs.close
rs.closed? # true

Low-level API

For those who prefer to define their own logging logic, Rotoscope also provides a low-level API. This is the same one used by Rotoscope::CallLogger internally. Users may specify a block that is invoked on each detected method call.

• .new
• #trace
• #start_trace
• #stop_trace
• #tracing?
• #receiver
• #receiver_class
• #receiver_class_name
• #method_name
• #singleton_method?
• #caller_object
• #caller_class
• #caller_class_name
• #caller_method_name
• #caller_singleton_method?
• #caller_path
• #caller_lineno

Rotoscope.new(&blk)

Creates a new instance of the Rotoscope class. The block argument is invoked on every call detected by Rotoscope. The block is passed the same instance returned by Rotoscope#new allowing the low-level methods to be called.

rs = Rotoscope.new do |call|
  # We likely don't want to record calls to Rotoscope
  return if self == call.receiver
  ...
end

Rotoscope#trace(&blk)

The equivalent of calling Rotoscope#start_trace and then Rotoscope#stop_trace. The call to #stop_trace is within an ensure block so it is always called when the block terminates.

rs = Rotoscope.new do |call|
  ...
end

rs.trace do
  # call some code
end

Rotoscope#start_trace

Begins detecting method calls invoked after this point.

rs = Rotoscope.new do |call|
  ...
end

rs.start_trace
# Calls after this points invoke the
# block passed to `Rotoscope.new`

Rotoscope#stop_trace

Disables method call detection invoked after this point.

rs = Rotoscope.new do |call|
  ...
end

rs.start_trace
...
rs.stop_trace
# Calls after this points will no longer
# invoke the block passed to `Rotoscope.new`

Rotoscope#tracing?

Identifies whether the Rotoscope object is actively tracing method calls.

rs = Rotoscope.new do |call|
  ...
end

rs.tracing? # => false
rs.start_trace
rs.tracing? # => true

Rotoscope#receiver

Returns the object that the method is being called against.

rs = Rotoscope.new do |call|
  call.receiver # => #<Foo:0x00007fa3d2197c10>
end

Rotoscope#receiver_class

Returns the class of the object that the method is being called against.

rs = Rotoscope.new do |call|
  call.receiver_class # => Foo
end

Rotoscope#receiver_class_name

Returns the stringified class of the object that the method is being called against.

rs = Rotoscope.new do |call|
  call.receiver_class_name # => "Foo"
end

Rotoscope#method_name

Returns the name of the method being invoked.

rs = Rotoscope.new do |call|
  call.method_name # => "bar"
end

Rotoscope#singleton_method?

Returns true if the method called is defined at the class level. If the call is to an instance method, this returns false.

rs = Rotoscope.new do |call|
  call.singleton_method? # => false
end

Rotoscope#caller_object

Returns the object whose context we invoked the call from.

rs = Rotoscope.new do |call|
  call.caller_object # => #<SomeClass:0x00008aa6d2cd91b61>
end

Rotoscope#caller_class

Returns the class of the object whose context we invoked the call from.

rs = Rotoscope.new do |call|
  call.caller_class # => SomeClass
end

Rotoscope#caller_class_name

Returns the tringified class of the object whose context we invoked the call from.

rs = Rotoscope.new do |call|
  call.caller_class_name # => "SomeClass"
end

Rotoscope#caller_method_name

Returns the stringified class of the object whose context we invoked the call from.

rs = Rotoscope.new do |call|
  call.caller_method_name # => "call_foobar"
end

Rotoscope#caller_singleton_method?

Returns true if the method invoking the call is defined at the class level. If the call is to an instance method, this returns false.

rs = Rotoscope.new do |call|
  call.caller_singleton_method? # => true
end

Rotoscope#caller_path

Returns the path to the file where the call was invoked.

rs = Rotoscope.new do |call|
  call.caller_path # => "/rotoscope_test.rb"
end

Rotoscope#caller_lineno

Returns the line number corresponding to the #caller_path where the call was invoked. If unknown, returns -1.

rs = Rotoscope.new do |call|
  call.caller_lineno # => 113
end