rublique 0.0.1

data/README

@@ -0,0 +1,83 @@
+Hello.  I'm going to answer the one question I expect to get asked regarding
+this package.  Hopefully everything else you can figure out from the RDoc.
+
+That question is:
+
+How do I use this with Rails?
+
+Well, for now, it's an ugly hack.  I don't know Rails internals well enough
+to come up with a better solution.
+
+The Rublique distribution includes a rublique_dispatcher.rb file which contains
+a replacement implementation for Dispatcher.dispatch compatible with
+Rails 1.1.6 (other versions may work.  I don't know)
+
+If you know a better way to do this, than for the love of God please e-mail
+me at tony@clickcaster.com (and no, sticking it in environment.rb won't work)
+
+First, find your gems directory (/usr/lib/ruby/gems, /usr/local/lib/ruby/gems,
+/opt/local/lib/ruby/gems, etc. depending on your platform)
+
+Then, look underr gems/1.8/gems/rails-1.1.6/lib directory and you'll find
+dispatcher.rb
+
+At the BOTTOM of this file, add:
+
+require 'rublique_dispatcher'
+
+Then restart your Rails application.
+
+This will log to RAILS_ROOT/log/rublique.log by default.  The format is a
+series of newline delimited JSON arrays, containing:
+
+[timestamp,{section breakdown}]
+
+The section breakdown is a JSON object which keys code section names (which
+with the Rails instrumentation will be in the form of "controller/action" or
+"rails" for anything done outside the dispatcher.  Each section name keys
+to another JSON object, with class names that key to an object count.
+
+The object count represents how many objects of a given class were created
+in that particular section minus how many objects of a given class originally
+created within that section were garbage collected since the last time
+the object counts were logged.  By default these deltas are logged every
+10 requests, and right now there's no good way to change that besides
+hand-editing rublique_dispatcher.rb (this is a 0.0.1 release, after all)
+
+That information probably isn't very useful to you, but fortunately Rublique
+includes a log analyzer tool that outputs CSV files you can import into
+the graphing tool of your choice.
+
+Run:
+
+rublique_analyzer -s rublique.log
+
+to output a breakdown of net object creation by code section over time.  The
+first column represents time in seconds, and the others object counts.
+
+To inspect a particular section, use:
+
+rublique_analyzer -c controller/action rublique.log
+
+This will give you a CSV breakdown of object allocation by class per code 
+section over time.
+
+---
+
+Known bugs:
+
+Rublique is neither thread safe nor reentrant.  This can lead to some erroneous
+numbers when used in a threaded environment (which is pretty much guaranteed
+with Rails)
+
+Rublique provides no interface for nor keeps a stack of code sections.  This
+means it presently only works within a dispatcher-like framework where
+you have an outer environment section which dispatches to various inner
+processing sections.  Sections can be no deeper than two levels.
+
+Because of this, things like Rails components will mess up Rublique's
+housekeeping.  Rublique really needs to keep a stack of code sections, and have
+a .pop method to move down a level.  That will have to wait for a future 
+version, sorry folks.
+
+For now: don't use components!

data/Rakefile

@@ -0,0 +1,33 @@
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'spec/rake/spectask'
+
+Spec::Rake::SpecTask.new(:spec) do |task|
+    task.spec_files = FileList['**/*_spec.rb']
+end
+
+Rake::RDocTask.new(:rdoc) do |task|
+    task.rdoc_dir = 'doc'
+    task.title    = 'Rublique'
+    task.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s|
+  s.name = %q{rublique}
+  s.version = "0.0.1"
+  s.date = %q{2006-12-19}
+  s.summary = %q{Rublique monitors object lifetimes across various code sections, outputting a logfile of object deltas which can be used to generate CSV files of object use over time}
+  s.email = %q{tony@clickcaster.com}
+  s.homepage = %q{http://rublique.rubyforge.org}
+  s.rubyforge_project = %q{rublique}
+  s.has_rdoc = true
+  s.authors = ["Tony Arcieri"]
+  s.files = ["README", "Rakefile", "lib", "lib/rublique.rb", "lib/rublique_logger.rb", "lib/rublique_dispatcher.rb", "bin", "bin/rublique_analyzer"]
+  s.add_dependency('json', '>= 0.4.0')
+  s.executables << 'rublique_analyzer'
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_tar = true
+end

data/bin/rublique_analyzer

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+
+begin
+  require 'fjson'
+rescue
+  require 'json'
+end
+
+logfile_name = ARGV.pop
+mode = nil
+
+case ARGV.shift
+when '-s'
+  mode = :sections
+when '-c'
+  mode = :classes
+  section_name = ARGV.shift
+end
+
+if !logfile_name || !mode || (mode == :classes && !section_name)
+  puts <<EOD
+Usage: #{$0} -s <logfile>
+       #{$0} -c <section> <logfile>
+
+#{$0} outputs a CSV analysis of a Rublique log:
+
+-s          Outputs a timestamp followed by every section in the logfile and
+            the total objects allocated by that section at that time
+
+-c section  Outputs a timestamp followed by how many instances of every class
+            are presently allocated within that section
+EOD
+  exit
+end
+
+logfile = File.open logfile_name, 'r'
+
+initial_time = nil
+output_data = []
+previous_totals = Hash.new(0)
+
+logfile.each_line do |line|
+  date, breakdown = JSON.parse line
+
+  if initial_time
+    tdelta = (Time.parse(date) - initial_time).to_i
+  else
+    tdelta = 0
+    initial_time = Time.parse(date)
+  end
+
+  case mode
+  when :sections
+    totals = breakdown.inject(previous_totals) do |h, action| 
+      name, objects = action
+      h[name] += objects.values.inject(0) { |a,v| a + v }
+      h
+    end
+  when :classes
+    next if breakdown[section_name].nil?
+
+    totals = breakdown[section_name].inject(previous_totals) do |h, classcounts| 
+      classname, count = classcounts
+      h[classname] += count
+      h
+    end
+  end
+
+  previous_totals = totals.dup
+  output_data << [tdelta, totals]
+end
+
+all_columns = output_data.last[1].keys.sort
+
+lifetime_totals = all_columns.inject({}) do |h,c| 
+  h[c] = output_data.inject(0) { |a,o| o[1][c] + a }
+  h
+end
+
+ranked_columns = lifetime_totals.sort { |a,b| b[1] <=> a[1] }.map { |a| a.shift }
+
+puts "seconds," + ranked_columns.join(',')
+
+output_data.each do |snapshot|
+  time, totals = snapshot
+  puts time.to_s + ',' + ranked_columns.map { |c| totals[c].to_s }.join(',')
+end

data/lib/rublique.rb

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+
+class Rublique
+  class << self
+    # A map of what objects belong to what tag
+    @@object_map = {}
+    
+    # A map of what classes belong(ed) to what ID
+    @@class_map = {}
+    
+    # A list of object counts, broken down by tag
+    @@object_breakdown = {}
+ 
+    # Grab the #object_id method from Ojbect, in case it's been overridden
+    # Objects like Builder::XmlMarkup do this
+    @@object_id_method = Object.new.method(:object_id).unbind
+
+    # Grab the #class method from Object, in case it's been overridden
+    @@class_method = Object.new.method(:class).unbind
+
+    # Take a snapshot of the current ObjectSpace, returning active object IDs and their associated tag
+    def snapshot(tag)
+      # Unknown stuff in ObjectSpace gets dumped here
+      new_objects = {}
+
+      # A list of stuff we know about, so we can see what got GCed
+      object_list = @@object_map.dup
+
+      ObjectSpace.each_object do |obj|
+        # Bind Object#object_id to the object and call it to get its id
+        obj_id = @@object_id_method.bind(obj).call
+        
+        if object_list.has_key? obj_id
+          # Delete known objects, since this list stores GCed objects
+          object_list.delete obj_id
+          next
+        end
+
+        # Add to the new objects collection if unknown, with the given tag
+        new_objects[obj_id] = tag
+
+        # Check to see if Object#class has been overridden
+        if obj.class.class == Class
+          @@class_map[obj_id] = obj.class
+        else
+          # Capture the real class of objects which override #class
+          @@class_map[obj_id] = @@class_method.bind(obj).call
+        end
+      end
+
+      # Remove objects that are no longer in ObjectSpace
+      object_list.each_key { |key| @@object_map.delete key }
+    
+      @@object_map.merge! new_objects
+    end
+    
+    # Return a hash of object IDs to their associated tag
+    def objects
+      @@object_map
+    end
+    
+    # Build a hash of hashes which maps a tag to its respective object IDs and those IDs to their class
+    def breakdown
+      @@object_map.to_a.inject({}) do |tag_hash, object_mapping|
+        obj, tag = object_mapping
+        
+        if tag_hash.has_key? tag
+          tag_hash[tag][obj] = @@class_map[obj]
+        else
+          tag_hash[tag] = { obj => @@class_map[obj] }
+        end
+        
+        tag_hash
+      end
+    end
+ 
+    # Build a hash of hashes which records total objects created and destroyed since the last delta was taken, by class by code section
+    def delta
+      old_object_breakdown = @@object_breakdown
+      @@object_breakdown = nil
+       
+      # Try to GC our own overhead
+      ObjectSpace.garbage_collect
+       
+      @@object_breakdown = breakdown
+       
+      @@object_breakdown.keys.inject({}) do |d, tag|
+        old_objects = old_object_breakdown[tag] || {}
+        new_objects = @@object_breakdown[tag]
+        
+        # Find objects which have been garbage collected, note them, and delete them from the class_map 
+        d[tag] = (old_objects.keys - new_objects.keys).inject(Hash.new(0)) do |h,obj| 
+          h[@@class_map[obj]] -= 1
+          @@class_map.delete obj
+          h
+        end
+        
+        new_objects.keys.inject(d[tag]) do |h,obj|
+          unless old_objects.has_key? obj
+            h[@@class_map[obj]] += 1
+          end
+          h
+        end.delete_if { |k,v| v == 0 }   
+        d
+      end.delete_if { |k,v| v.empty? }
+    end
+  end
+end

data/lib/rublique_dispatcher.rb

@@ -0,0 +1,44 @@
+require 'rublique'
+require 'rublique_logger'
+
+RUBLIQUE_LOG_INTERVAL = 10
+
+# Override the Rails 1.1.6 dispatcher to use Rublique
+class Dispatcher
+  # Set the Rublique logfile path if we haven't already
+  @@logfile_path_set = false
+
+  # Count the number of requests we've received before logging a delta
+  @@request_count = RUBLIQUE_LOG_INTERVAL
+
+  def self.dispatch(cgi = nil, session_options = ActionController::CgiRequest::DEFAULT_SESSION_OPTIONS, output = $stdout)
+    # Set the logfile path to within RAILS_ROOT
+    unless @@logfile_path_set
+      RubliqueLogger.file = RAILS_ROOT + '/log/rublique.log'
+      @@logfile_path_set = true
+    end
+
+    if cgi ||= new_cgi(output)
+      request, response = ActionController::CgiRequest.new(cgi, session_options), ActionController::CgiResponse.new(cgi)
+      prepare_application
+
+      # Locate the appropriate controller through routes
+      controller = ActionController::Routing::Routes.recognize!(request)
+
+      Rublique.snapshot('rails')
+      controller.process(request, response).out(output)
+      Rublique.snapshot(controller.controller_name + '/' + controller.action_name)
+
+      @@request_count += 1
+      @@request_count = 0 if @@request_count > RUBLIQUE_LOG_INTERVAL
+      RubliqueLogger.log if @@request_count == 0
+    end
+  rescue Object => exception
+    failsafe_response(output, '500 Internal Server Error', exception) do
+      ActionController::Base.process_with_exception(request, response, exception).out(output)
+    end
+  ensure
+    # Do not give a failsafe response here.
+    reset_after_dispatch
+  end
+end

data/lib/rublique_logger.rb

@@ -0,0 +1,38 @@
+require 'rubygems'
+require 'rublique'
+
+begin
+  require 'fjson'
+rescue
+  require 'json'
+end
+
+# A singleton for writing logs Rublique deltas in JSON format to be used in
+# conjunction with rublique_analyzer
+class RubliqueLogger
+  class << self
+    # Path to logfile
+    @@path = '/tmp/rublique.log'
+
+    # Logfile handle
+    @@log = nil
+
+    # Set the logfile name.  May only be done before .log is called
+    def file=(path)
+      raise 'Cannot change Railique log path after logfile has been opened' unless @@log.nil?
+      @@path = path
+    end
+
+    # Log a Rublique delta
+    def log
+      if @@log.nil?
+        @@log = File.open(@@path, 'a+')
+        @@log.sync = true
+      end
+
+      delta = Rublique.delta
+      @@log.write [Time.now.strftime('%Y-%m-%d %H:%M:%S'), delta].to_json + "\n" unless delta.empty?
+      delta
+    end
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.0
+specification_version: 1
+name: rublique
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+date: 2006-12-19 00:00:00 -07:00
+summary: Rublique monitors object lifetimes across various code sections, outputting a logfile of object deltas which can be used to generate CSV files of object use over time
+require_paths: 
+- lib
+email: tony@clickcaster.com
+homepage: http://rublique.rubyforge.org
+rubyforge_project: rublique
+description: 
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Tony Arcieri
+files: 
+- README
+- Rakefile
+- lib
+- lib/rublique.rb
+- lib/rublique_logger.rb
+- lib/rublique_dispatcher.rb
+- bin
+- bin/rublique_analyzer
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: 
+- rublique_analyzer
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.4.0
+    version: