bleak_house 3 → 3.0.1

data/CHANGELOG

@@ -1,7 +1,29 @@
 
-BleakHouse Changelog
+v3.0.1. Rewrite. Remove Gruffs and graphs. Become a standard compiled extension. Walk the symbol table. Track object histories. Use custom CSV format instead of YAML.
 
-3. gem version
-2. dumped Rublique once I understood what it did; replaced with a lightweight non-delta marshalling version
-1. first version
+v2.7. Version renumbering; apologies if this messes anyone up.
+
+v2.6. RDoc documentation; use new Echoe setup; fix for namespaced controllers.
+
+v2.5. Detect if core keys are present or not; fixes for analyzing non-Rails apps.
+
+v2.4. Log heap usage; remove pure-Ruby profiler.
+
+v2.3. Subtract Rails core counts from action counts and join paired frames.
+
+v2.2. Change smoothing algorithm to be more intuitive and so mem usage is correct.
+
+v2.1. Close file properly.
+
+v2. C instrumentation with YAML output.
+
+v1.3. Log memory usage on *nix.
+
+v1.2. Fix nil directory traversal error on Windows.
+
+v1.1. Gem version
+
+v1. Dumped Rublique; replaced with a lightweight non-delta marshalling version.
+
+v0. First version
 

data/LICENSE_BSD

@@ -0,0 +1,10 @@
+
+Copyright 2006, Eric Hodel. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+   2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+   3. Neither the names of the authors nor the names of their contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS?? AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/LICENSE_RUBY

@@ -0,0 +1,53 @@
+$BK\%W%m%0%i%`$O%U%j!<%=%U%H%&%'%"$G$9!%(BGPL(the GNU General
+Public License)$B$^$?$O0J2<$K<($9>r7o$GK\%W%m%0%i%`$r:FG[I[$G(B
+$B$-$^$9!%(BGPL$B$K$D$$$F$O(BCOPYING.txt$B%U%!%$%k$r;2>H$7$F2<$5$$!%(B
+
+  1. $BJ#@=$O@)8B$J$/<+M3$G$9!%(B
+
+  2. $B0J2<$N>r7o$N$$$:$l$+$rK~$?$9;~$KK\%W%m%0%i%`$N%=!<%9$r(B
+     $B<+M3$KJQ99$G$-$^$9!%(B
+
+     (a) $B%M%C%H%K%e!<%:$K%]%9%H$7$?$j!$:n<T$KJQ99$rAwIU$9$k(B
+         $B$J$I$NJ}K!$G!$JQ99$r8x3+$9$k!%(B
+
+     (b) $BJQ99$7$?K\%W%m%0%i%`$r<+J,$N=jB0$9$kAH?%FbIt$@$1$G(B
+         $B;H$&!%(B
+
+     (c) $BJQ99E@$rL@<($7$?$&$(!$%=%U%H%&%'%"$NL>A0$rJQ99$9$k!%(B
+         $B$=$N%=%U%H%&%'%"$rG[I[$9$k;~$K$OJQ99A0$NK\%W%m%0%i(B
+         $B%`$bF1;~$KG[I[$9$k!%$^$?$OJQ99A0$NK\%W%m%0%i%`$N%=!<(B
+         $B%9$NF~<jK!$rL@<($9$k!%(B
+
+     (d) $B$=$NB>$NJQ99>r7o$r:n<T$H9g0U$9$k!%(B
+
+  3. $B0J2<$N>r7o$N$$$:$l$+$rK~$?$9;~$KK\%W%m%0%i%`$r%3%s%Q%$(B
+     $B%k$7$?%*%V%8%'%/%H%3!<%I$d<B9T7A<0$G$bG[I[$G$-$^$9!%(B
+
+     (a) $B%P%$%J%j$r<u$1<h$C$??M$,%=!<%9$rF~<j$G$-$k$h$&$K!$(B
+         $B%=!<%9$NF~<jK!$rL@<($9$k!%(B
+
+     (b) $B5!3#2DFI$J%=!<%9%3!<%I$rE:IU$9$k!%(B
+
+     (c) $BJQ99$r9T$C$?%P%$%J%j$OL>A0$rJQ99$7$?$&$(!$%*%j%8%J(B
+         $B%k$N%=!<%9%3!<%I$NF~<jK!$rL@<($9$k!%(B
+
+     (d) $B$=$NB>$NG[I[>r7o$r:n<T$H9g0U$9$k!%(B
+
+  4. $BB>$N%W%m%0%i%`$X$N0zMQ$O$$$+$J$kL\E*$G$"$l<+M3$G$9!%$?(B
+     $B$@$7!$K\%W%m%0%i%`$K4^$^$l$kB>$N:n<T$K$h$k%3!<%I$O!$$=(B
+     $B$l$>$l$N:n<T$N0U8~$K$h$k@)8B$,2C$($i$k>l9g$,$"$j$^$9!%(B
+
+     $B6qBNE*$K$O(Bgc.c($B0lIt(B)$B!$(Butil.c($B0lIt(B)$B!$(Bst.[ch]$B!$(Bregex.[ch] 
+     $B$*$h$S(B ./missing$B%G%#%l%/%H%j2<$N%U%!%$%k72$,3:Ev$7$^$9!%(B
+     $B$=$l$>$l$NG[I[>r7o$J$I$KIU$$$F$O3F%U%!%$%k$r;2>H$7$F$/(B
+     $B$@$5$$!%(B
+
+  5. $BK\%W%m%0%i%`$X$NF~NO$H$J$k%9%/%j%W%H$*$h$S!$K\%W%m%0%i(B
+     $B%`$+$i$N=PNO$N8"Mx$OK\%W%m%0%i%`$N:n<T$G$O$J$/!$$=$l$>(B
+     $B$l$NF~=PNO$r@8@.$7$??M$KB0$7$^$9!%$^$?!$K\%W%m%0%i%`$K(B
+     $BAH$_9~$^$l$k$?$a$N3HD%%i%$%V%i%j$K$D$$$F$bF1MM$G$9!%(B
+
+  6. $BK\%W%m%0%i%`$OL5J]>Z$G$9!%:n<T$OK\%W%m%0%i%`$r%5%]!<%H(B
+     $B$9$k0U;V$O$"$j$^$9$,!$%W%m%0%i%`<+?H$N%P%0$"$k$$$OK\%W(B
+     $B%m%0%i%`$N<B9T$J$I$+$iH/@8$9$k$$$+$J$kB;32$KBP$7$F$b@U(B
+     $BG$$r;}$A$^$;$s!%(B

data/Manifest

@@ -1,18 +1,30 @@
-./CHANGELOG
-./LICENSE
-./Manifest
-./README
-./Rakefile
-./init.rb
-./install.rb
-./lib/bleak_house
-./lib/bleak_house/action_controller.rb
-./lib/bleak_house/analyze.rb
-./lib/bleak_house/bleak_house.rb
-./lib/bleak_house/dispatcher.rb
-./lib/bleak_house/gruff_hacks.rb
-./lib/bleak_house/mem_logger.rb
-./lib/bleak_house/rake_task_redefine_task.rb
-./lib/bleak_house/support_methods.rb
-./lib/bleak_house.rb
-./tasks/bleak_house_tasks.rake
+TODO
+test/unit/test_bleak_house.rb
+test/misc/direct.rb
+README
+Rakefile
+patches/parse.y.patch
+patches/gc.c.patch
+Manifest
+LICENSE_RUBY
+LICENSE_BSD
+LICENSE
+lib/vendor/lightcsv.rb
+lib/bleak_house.rb
+lib/bleak_house/support/rake.rb
+lib/bleak_house/support/core_extensions.rb
+lib/bleak_house/rails.rb
+lib/bleak_house/rails/dispatcher.rb
+lib/bleak_house/rails/bleak_house.rb
+lib/bleak_house/rails/action_controller.rb
+lib/bleak_house/logger.rb
+lib/bleak_house/logger/mem_usage.rb
+lib/bleak_house/analyzer.rb
+lib/bleak_house/analyzer/analyzer.rb
+install.rb
+init.rb
+ext/bleak_house/logger/snapshot.h
+ext/bleak_house/logger/snapshot.c
+ext/bleak_house/logger/extconf.rb
+CHANGELOG
+bin/bleak

data/README

@@ -1,20 +1,73 @@
------------------------------------------------------------------
 
 BleakHouse
-You need the 'gruff' gem, and 'rmagick', and all that.
 
-To run:
-  RAILS_ENV=production BLEAK_HOUSE=true INTERVAL=5 ./script/server 
-Browse around in your app. Cause requests. Do stuff. Then:
-  RAILS_ENV=production rake bleak_house:analyze
-And then look in log/bleak_house/.
+A library for finding memory leaks. 
 
-Copyright (c) 2007 Cloudburst, LLC. See included LICENSE file. Portions
-copyright Tony Arcieri and Scott Barron and used under license.
+== License
+
+Copyright 2007 Cloudburst, LLC. See the included LICENSE file. Portions copyright 2006 Eric Hodel and used with permission. See the included LICENSE_BSD file. Portions copyright 2007 TOMITA Masahiro and used with permission. See the included LICENSE_RUBY file.
+
+The public certificate for this gem is at http://rubyforge.org/frs/download.php/25331/evan_weaver-original-public_cert.pem.
+
+== Features
+
+* leak-proof C instrumentation
+* fast logging
+* complete tracking of object and symbol history
+* easy Rails integration
+
+== Requirements
+
+* A unix-like operating system
+* Ruby 1.8.6
+
+= Usage
+
+== Installation
+
+Install the gem:
+  sudo gem install bleak_house -v 3.0.1
+
+You need to compile the BleakHouse patched Ruby build. In the plugin directory, run:
+  rake ruby:build
+  
+This gives you a Ruby binary named <tt>ruby-bleak-house</tt> alongside your regular binary.
+
+== Profiling a Rails app
+
+To setup a Rails app for profiling, just <tt>require 'bleak_house'</tt> in <tt>config/environment.rb</tt>.
+
+Then, to engage the logger (ideally, in a live deployment situation), start a server instance as so:
+  RAILS_ENV=production BLEAK_HOUSE=true ruby-bleak-house ./script/server 
+
+Browse around manually, thrash your entire app with a script, target troublesome controllers/actions, etc. The BleakHouse logger will dump a huge amount of data to <tt>log/bleak_house_production.dump</tt>--keep an eye on your disk space.
+
+Then, to analyze the dump:
+  bleak path/to/log/bleak_house_production.dump
   
-I was such a shy little thing that I seldom dared to open my lips, and never 
-dared to open my heart, to anybody else.
-- Dickens, Bleak House
+Be patient.
+
+= Extras
+
+== Using BleakHouse outside of Rails
+
+Just instantiate a BleakHouse::Logger object, and make calls to <tt>snapshot</tt> at appropriate times.
+
+== Troubleshooting
+
+If you see the error <tt>Symbol not found: _rb_gc_heaps_used</tt>, it means you installed the patched binary, but tried to profile the server with the regular Ruby binary.
+
+You may get library require errors if you install <tt>ruby-bleak-house</tt> 1.8.6 alongside a different verson of Ruby. You could try to patch your local version of Ruby instead, or you could just upgrade to 1.8.6, which has a good trackrecord of stability.
+
+== Reporting problems
+
+* http://rubyforge.org/forum/forum.php?forum_id=13983
+
+Patches and contributions are very welcome. Please note that contributors are required to assign copyright for their additions to Cloudburst, LLC.
+
+== Further resources
 
------------------------------------------------------------------
+* http://blog.evanweaver.com/articles/2007/05/12/let-me-hit-you-with-some-knowledge
+* http://blog.evanweaver.com/articles/2007/05/06/leak-proof-direct-heap-instrumentation-for-bleak_house
+* http://blog.evanweaver.com/articles/2007/04/28/bleak_house
 

data/Rakefile

@@ -1,66 +1,73 @@
-require 'rubygems'
-require 'rake'
-require 'lib/bleak_house/rake_task_redefine_task'
 
-NAME = "bleak_house"
+require 'lib/bleak_house/support/rake'
 
 begin
-  require 'rake/clean'
-  gem 'echoe', '>= 1.1'
   require 'echoe'
-  require 'fileutils'
-
-  AUTHOR = "Evan Weaver"
-  EMAIL = "evan at cloudbur dot st"
-  DESCRIPTION = "BleakHouse is a Rails plugin for finding memory leaks. It tracks ObjectSpace for your entire app, and produces charts of references by controller, by action, and by object class."
-  CHANGES = `cat CHANGELOG`[/^([\d\.]+\. .*)/, 1]
-  RUBYFORGE_NAME = "fauna"
-  GEM_NAME = "bleak_house" 
-  HOMEPATH = "http://blog.evanweaver.com"
-  RELEASE_TYPES = ["gem"]
-  REV = nil
-  VERS = `cat CHANGELOG`[/^([\d\.]+)\. /, 1]
-  CLEAN.include ['**/.*.sw?', '*.gem', '.config']
-  RDOC_OPTS = ['--quiet', '--title', "bleak_house documentation", "--opname", "index.html", "--line-numbers", "--main", "README", "--inline-source"]
-  
-  include FileUtils
-  
-  taskmsg = File.open(File.dirname(__FILE__) + "/tasks/bleak_house_tasks.rake").readlines
-  taskmsg = taskmsg[0..3] + [taskmsg[7][2..-1]] + taskmsg[9..-1]
   
-  echoe = Echoe.new(GEM_NAME, VERS) do |p|
-    p.author = AUTHOR 
-    p.rubyforge_name = RUBYFORGE_NAME
-    p.name = NAME
-    p.description = DESCRIPTION
-    p.changes = CHANGES
-    p.email = EMAIL
-    p.summary = DESCRIPTION
-    p.url = HOMEPATH
-    p.need_tar = false
-    p.need_tar_gz = true
-    p.test_globs = ["*_test.rb"]
-    p.clean_globs = CLEAN  
-    p.spec_extras = {:post_install_message => 
-"
-Thanks for installing Bleak House #{VERS}. 
-
-For each Rails app you want to profile, you will need to add the following 
-rake task in RAILS_ROOT/lib/tasks/bleak_house_tasks.rake to be able to run 
-the analyzer: 
-" + taskmsg.join("  ") + "\n"}
+  Echoe.new("bleak_house") do |p|
+    p.author = "Evan Weaver" 
+    p.project = "fauna"
+    p.summary = "A library for finding memory leaks."
+    p.url = "http://blog.evanweaver.com/files/doc/fauna/bleak_house/"
+    p.docs_host = 'blog.evanweaver.com:~/www/bax/public/files/doc/'
+    p.rdoc_pattern = /^ext.*\.c|lib.*logger.*rb|analyzer|rails\/bleak_house|^README|^CHANGELOG|^TODO|^LICENSE|^COPYING$/
+    p.dependencies = ['rake']
+    p.require_signed = true
+    p.include_gemspec = false
+    p.include_rakefile = true      
   end
-            
-rescue LoadError => boom
-  puts "You are missing a dependency required for meta-operations on this gem."
-  puts "#{boom.to_s.capitalize}."
-  
-  desc 'Run the default tasks'
-  task :default => :test
+         
+rescue LoadError
 end
 
-desc 'Do nothing.'
+desc 'Run tests.'
 Rake::Task.redefine_task("test") do
-   puts "There are no tests. You could totally write some, though."
-#   system "ruby -Ibin:lib:test test/unit/polymorph_test.rb #{ENV['METHOD'] ? "--name=#{ENV['METHOD']}" : ""}"
+  system "ruby-bleak-house -Ibin:lib:test test/unit/test_bleak_house.rb #{ENV['METHOD'] ? "--name=#{ENV['METHOD']}" : ""}"
 end
+
+desc 'Build a patched binary.'
+namespace :ruby do
+  task :build do    
+    if RUBY_PLATFORM =~ /win32|windows/
+      puts "ERROR: windows not supported."
+      exit
+    end
+    require 'fileutils'
+    puts "building patched Ruby binary"
+    tmp = "/tmp/"
+    Dir.chdir(tmp) do
+      build_dir = "bleak_house"
+      binary_dir = File.dirname(`which ruby`)
+      FileUtils.rm_rf(build_dir) rescue nil
+      Dir.mkdir(build_dir)
+      begin
+        Dir.chdir(build_dir) do
+          puts "  downloading Ruby source"
+          bz2 = "ruby-1.8.6.tar.bz2"
+          system("wget 'http://rubyforge.org/frs/download.php/18434/ruby-1.8.6.tar.bz2' &> wget.log")
+          puts "  extracting"
+          system("tar xjf #{bz2} &> tar.log")
+          File.delete bz2
+          Dir.chdir("ruby-1.8.6") do
+            puts "  patching"
+            system("patch -p0 < \'#{File.dirname(__FILE__)}/patches/gc.c.patch\' &> ../gc.c.patch.log")
+            system("patch -p0 < \'#{File.dirname(__FILE__)}/patches/parse.y.patch\' &> ../parse.y.patch.log")
+            puts "  configuring"
+            system("./configure --prefix=#{binary_dir[0..-5]} &> ../configure.log") # --with-static-linked-ext
+            puts "  making"
+            system("make &> ../make.log")
+  
+            binary = "#{binary_dir}/ruby-bleak-house"
+            puts "  installing as #{binary}"
+            FileUtils.cp("./ruby", binary)
+            FileUtils.chmod(0755, binary)
+            puts "  done"
+          end
+        end
+      rescue Object => e
+        puts "ERROR: please see the last modified log file in #{tmp}#{build_dir}, perhaps\nit will contain a clue."
+      end    
+    end    
+  end
+end
+

data/TODO

@@ -0,0 +1,2 @@
+
+* Per-object memory usage. This may be impossible to do accurately.

data/bin/bleak

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+unless ARGV[0]
+  puts "Please specify a BleakHouse logfile"
+  exit
+else    
+  $LOAD_PATH << "#{File.dirname(__FILE__)}/../lib/"
+  require 'bleak_house/analyzer'
+  BleakHouse::Analyzer.run(ARGV[0])
+end

data/ext/bleak_house/logger/extconf.rb

@@ -0,0 +1,4 @@
+
+require 'mkmf'
+dir_config('snapshot')
+create_makefile('bleak_house/logger/snapshot')

data/ext/bleak_house/logger/snapshot.c

@@ -0,0 +1,153 @@
+
+#include "snapshot.h"
+
+static VALUE rb_mBleakHouse;
+static VALUE rb_cC;
+
+/* Number of struct heaps_slots used */
+static VALUE heaps_used(VALUE self) {
+  return INT2FIX(rb_gc_heaps_used());
+}
+
+/* Length of the struct heaps_slots allocated */
+static VALUE heaps_length(VALUE self) {
+  return INT2FIX(rb_gc_heaps_length());
+}
+
+/* Count the live objects on the heap and in the symbol table and write a CSV frame to <tt>_logfile</tt>. Set <tt>_specials = true</tt> if you also want to count AST nodes and var scopes; otherwise, use <tt>false</tt>. Note that common classes in the CSV output are hashed to small integers in order to save space.*/
+static VALUE snapshot(VALUE self, VALUE _logfile, VALUE tag, VALUE _specials) {
+  Check_Type(_logfile, T_STRING);
+  Check_Type(tag, T_STRING);
+
+  RVALUE *obj, *obj_end;
+  st_table_entry *sym, *sym_end;
+  
+  struct heaps_slot * heaps = rb_gc_heap_slots();
+  struct st_table * sym_tbl = rb_parse_sym_tbl();
+
+  int specials = RTEST(_specials);
+  int hashed;
+
+  /* see if the logfile exists already */
+  FILE *logfile = fopen(StringValueCStr(_logfile), "r");
+  int is_new;
+  if (!(is_new = (logfile == NULL)))
+    fclose(logfile);
+
+  /* reopen for writing */
+  if ((logfile = fopen(StringValueCStr(_logfile), "a+")) == NULL)
+    rb_raise(rb_eRuntimeError, "couldn't open snapshot file");
+
+  /* write the time */
+  fprintf(logfile, "-1,%i\n", time(0));
+  
+  /* get and write the memory usage */
+  VALUE mem = rb_funcall(self, rb_intern("mem_usage"), 0);
+  fprintf(logfile, "-2,%i\n", NUM2INT(RARRAY_PTR(mem)[0]));
+  fprintf(logfile, "-3,%i\n", NUM2INT(RARRAY_PTR(mem)[1]));
+  
+  int current_pos = 0;  
+  int filled_slots = 0;
+  int free_slots = 0;
+
+  /* write the tag header */
+  fprintf(logfile, "-4,%s\n", StringValueCStr(tag));
+
+  int i, j;
+  
+  /* walk the heap */
+  for (i = 0; i < rb_gc_heaps_used(); i++) {
+    obj = heaps[i].slot;
+    obj_end = obj + heaps[i].limit;
+    for (; obj < obj_end; obj++) {
+      if (obj->as.basic.flags) { /* always 0 for freed objects */
+        filled_slots ++;
+        switch (TYPE(obj)) {
+          case T_NONE:
+              hashed = BUILTINS_SIZE + 0; break;
+          case T_BLKTAG:
+              hashed = BUILTINS_SIZE + 1; break;
+          case T_UNDEF:
+              hashed = BUILTINS_SIZE + 2; break;
+          case T_VARMAP:
+              hashed = BUILTINS_SIZE + 3; break;
+          case T_SCOPE:
+              hashed = BUILTINS_SIZE + 4; break;
+          case T_NODE:
+              hashed = BUILTINS_SIZE + 5; break;
+          default:
+            if (!obj->as.basic.klass) {
+              hashed = BUILTINS_SIZE + 6;
+            } else {
+              hashed = lookup_builtin(rb_obj_classname((VALUE)obj));
+            }
+        }
+        /* write to log */
+        if (hashed < 0) {
+          /* regular classname */
+          fprintf(logfile, "%s,%lu\n", rb_obj_classname((VALUE)obj), FIX2ULONG(rb_obj_id((VALUE)obj)));
+        } else {
+          /* builtins key */
+          if (specials || hashed < BUILTINS_SIZE) {
+            /* 0 is not used for 'hashed' because Ruby's to_i turns any String into 0 */
+            fprintf(logfile, "%i,%lu\n", hashed + 1, FIX2ULONG(rb_obj_id((VALUE)obj)));
+          }
+        }
+      } else {
+        free_slots ++;
+      }
+    }
+  }
+  
+  /* walk the symbol table */
+  hashed = lookup_builtin("Symbol");
+  for (i = 0; i < sym_tbl->num_bins; i++) {
+    for (sym = sym_tbl->bins[i]; sym != 0; sym = sym->next) {
+      fprintf(logfile, "%i,%lu\n", hashed + 1, sym->record);
+    }
+  }
+    
+  fprintf(logfile, "-5,%i\n", filled_slots);
+  fprintf(logfile, "-6,%i\n", free_slots);
+  fclose(logfile);
+    
+  rb_funcall(rb_mGC, rb_intern("start"), 0); /* request GC run */
+  return Qtrue;
+}
+
+int lookup_builtin(char * name) {
+  int i;
+  for (i = 0; i < BUILTINS_SIZE; i++) {
+    if (!strcmp(builtins[i], name)) return i;      
+  }
+  return -1;
+}
+
+/*
+
+This class performs the actual object logging of BleakHouse. To use it directly, you need to make calls to BleakHouse::Logger#snapshot. 
+
+== Example
+
+At the start of your app, put:
+  require 'rubygems'
+  require 'bleak_house'
+  $memlogger = BleakHouse::Logger.new
+  File.delete($logfile = "/path/to/logfile") rescue nil
+
+Now, at the points of interest, put:
+  $memlogger.snapshot($logfile, "tag/subtag", false)
+
+Run your app. Once you are done, analyze your data:
+  bleak /path/to/logfile
+  
+*/
+void
+Init_snapshot()
+{
+  rb_mBleakHouse = rb_define_module("BleakHouse");
+  rb_cC = rb_define_class_under(rb_mBleakHouse, "Logger", rb_cObject);
+  rb_define_method(rb_cC, "snapshot", snapshot, 3);
+  rb_define_method(rb_cC, "heaps_used", heaps_used, 0);
+  rb_define_method(rb_cC, "heaps_length", heaps_length, 0);
+}

data/ext/bleak_house/logger/snapshot.h

@@ -0,0 +1,99 @@
+#include "ruby.h"
+#include "env.h"
+#include "node.h"
+#include "st.h"
+#include "re.h"
+#include "util.h"
+#include "intern.h"
+#include "string.h"
+
+/* Histogram of most common Rails classes */
+static char * builtins[] = {
+ "String",
+ "Array",
+ "Hash",
+ "Class",
+ "Regexp",
+ "Proc",
+ "ActionController::Routing::DividerSegment",
+ "Gem::Version",
+ "Gem::Version::Requirement",
+ "Bignum",
+ "Symbol",
+ "Time",
+ "MatchData",
+ "Gem::Specification",
+ "ActionController::Routing::StaticSegment",
+ "Gem::Dependency",
+ "Module",
+ "ActionController::Routing::DynamicSegment",
+ "Range",
+ "ActionController::Routing::Route",
+ "Float",
+ "HashWithIndifferentAccess",
+ "Method",
+ "Enumerable",
+ "Comparable",
+ "Set",
+ "File",
+ "Object",
+ "NameError",
+ "Thread",
+  "_node",
+  "_none",
+  "_blktag",
+  "_undef",
+  "_varmap",
+  "_scope",
+  "_unknown" 
+};
+
+#define BUILTINS_SIZE 30
+#define SPECIALS_SIZE 7
+
+typedef struct RVALUE {
+    union {
+        struct {
+            unsigned long flags; /* always 0 for freed obj */
+            struct RVALUE *next;
+        } free;
+        struct RBasic  basic;
+        struct RObject object;
+        struct RClass  klass;
+        struct RFloat  flonum;
+        struct RString string;
+        struct RArray  array;
+        struct RRegexp regexp;
+        struct RHash   hash;
+        struct RData   data;
+        struct RStruct rstruct;
+        struct RBignum bignum;
+        struct RFile   file;
+        struct RNode   node;
+        struct RMatch  match;
+        struct RVarmap varmap;
+        struct SCOPE   scope;
+    } as;
+} RVALUE;
+
+struct heaps_slot {
+    void *membase;
+    RVALUE *slot;
+    int limit;
+};
+
+typedef struct st_table_entry st_table_entry;
+
+struct st_table_entry {
+    unsigned int hash;
+    st_data_t key;
+    st_data_t record;
+    st_table_entry *next;
+};
+
+struct st_table * rb_parse_sym_tbl();
+struct heaps_slot * rb_gc_heap_slots();
+int rb_gc_heaps_used();
+int rb_gc_heaps_length();
+
+int lookup_builtin(char *);

data/init.rb

@@ -1,2 +1,3 @@
 
-require 'bleak_house'
+puts "Please use the gem version of BleakHouse from now on."
+exit!

data/install.rb

@@ -1 +1,2 @@
-puts File.open("#{File.dirname(__FILE__)}/README").read
+
+puts "Please use the gem version of BleakHouse from now on."