Skip to content
High-performance logger of Ruby method invocations
Ruby C Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
bin
ext/rotoscope Add comment on why we need a different frame index for C and ruby calls Feb 27, 2019
lib
test
.clang-format
.gitignore
.rubocop.yml
.ruby-version Update dev.yml with ruby version changed in .ruby-version Feb 17, 2019
.travis.yml
Gemfile
LICENSE
README.md Updated README based on changes to the API May 16, 2018
Rakefile
dev.yml
rotoscope.gemspec update ruby code style Dec 19, 2018

README.md

Rotoscope

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

Status

Build Status Gem Version

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

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


Public Class Methods

Rotoscope::CallLogger::trace(dest, blacklist: [])

Writes all calls of methods to dest, except for those whose filepath contains any entry in blacklist. 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) { |rs| ... }
# or...
Rotoscope::CallLogger.trace(dest, blacklist: ["/.gem/"]) { |rs| ... }

Rotoscope::CallLogger::new(dest, blacklist: [])

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, blacklist: ["/.gem/"])

Public Instance Methods

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
You can’t perform that action at this time.