solutious-stella 0.5.5

data/CHANGES.txt

@@ -0,0 +1,36 @@
+STELLA, CHANGES
+
+
+#### 0.5.5 (2009-01-14) ###############################
+
+http://github.com/solutious/stella/tree/0.5.5
+
+* Now has specs (33 specifications, 303 requirements)
+* New dependency: test-spec (development copy only)
+* Added delano/drydock to vendor (was delano/frylock). 
+* Improved argument handling for load tool adapters (httperf not complete)
+* Re-built Stella::Storable and subclasses (now using "field" method)
+* Test::Stats, Test::Run::Summary cleanup
+* Fixed RubyGems require error
+* Fixed stddev bug by removing weak math, adding stats class from Mongrel
+* Fixed --agent error
+
+
+#### 0.5.4-alpha (2009-01-07) #########################
+
+http://github.com/solutious/stella/tree/0.5.4-alpha
+
+* New command: watch. Monitor HTTP traffic with Ruby-Pcap (unix only) or proxy. Pcap also supports DNS sniffing.
+* Improved error handling for stats output
+* Now runs on Ruby 1.9.1, JRuby
+* Added Windows support for most features
+* Added patch for Ruby-Pcap
+* Added friendly error handling for Apache Bench, Siege, and Httperf
+
+
+#### 0.5.3-preview (2008-12-23) #######################
+
+http://github.com/solutious/stella/tree/e4d2bd8db3d1323fbc3b8bbb7f703ce7b8c88551
+
+* Initial public release
+

data/README.textile

@@ -0,0 +1,162 @@
+h1. Stella - Your Performance Testing Friend
+
+Release: 0.5.5 (2009-01-14)
+
+This is a BETA release. Proceed in double verify mode!
+
+h2. Overview
+
+Stella is a command-line tool for running, reporting, and analyzing performance tests.
+
+
+h2. Prerequisites
+
+* Linux, BSD, Solaris
+* Ruby 1.8.x, 1.9.x, or JRuby 1.1
+* Native Libraries (c or c++) 
+** Pcap (optional, for packet sniffing)
+* Ruby Libraries
+** rspec
+** net-dns 
+** Ruby-Pcap (optional, for packet sniffing)
+
+* One of:
+** "Apache Bench":http://httpd.apache.org/docs/2.2/programs/ab.html
+** "Siege":http://www.joedog.org/index/siege-home
+** "Httperf":http://www.hpl.hp.com/research/linux/httperf/
+*** _Note: Argument handling for Httperf is incomplete_
+
+
+h2. Installation
+
+Get it in one of the following ways:
+
+* RubyForge: http://stella.rubyforge.org/
+** gem install stella 
+* git clone git://github.com/solutious/stella.git
+** git submodule init
+** git submodule update
+ 
+Use ab, siege, and httperf like you normally would with the addition of stella at the beginning (examples are below).
+
+h3. Debian (and derivatives)
+
+Debian and its derivative (Ubunutu) handling packing a bit differently (see: http://pkg-ruby-extras.alioth.debian.org/rubygems.html). There are a couple errors to watch out for during the installation. The solutions are below:
+
+  "no such file to load -- mkmf (LoadError)"
+	$ apt-get install ruby1.8-dev
+
+  "ERROR: RDoc documentation generator not installed!"
+	$ apt-get install rdoc
+
+
+h3. Installing libpcap and Ruby-Pcap
+
+*Stella currently supports packet filtering with Native Ruby (no JRuby) on Linux/Unix/OS X only.* 
+*Ruby-Pcap does not compile with Ruby 1.9.1-RC1*
+
+libpcap and Ruby-Pcap are used to by Stella's watch command to filter packets off the network. This allows you to view HTTP requests and response (including headers and content) without having to configure a proxy. Both need to be compiled and installed separately:
+* "libpcap":http://www.tcpdump.org/release/
+* "Ruby-Pcap":http://www.goto.info.waseda.ac.jp/~fukusima/ruby/pcap-e.html
+
+On Ruby, 1.8.6, Ruby-Pcap produces the following warnings at runtime: "pcap.bundle: warning: do not use Fixnums as Symbols". See: support/ruby-pcap-takuma-notes.txt. 
+  
+
+h2. Usage Examples
+
+  Run Apache Bench with a warmup and rampup from 10 to 20 virtual users in increments of 5
+  $ stella --warmup=0.5 --rampup=5,20 ab -c 10 -n 50 http://stellaaahhhh.com/search?term=trooper
+    
+  Run Siege, repeat the test 5 times. Automatically creates a summary averages and standard deviations. 
+  $ stella --agent=ff-3-osx --testruns=5  siege -c 10 -r 5 -b http://stellaaahhhh.com/search?term=flock+of+seagulls
+    
+  Run Httperf like you normally would (but all the test data will be collected for you)
+  $ stella httperf --hog --client=0/1 --server=127.0.0.1 --port=5600 --uri=/ --rate=50  --num-conns=100 --timeout=5
+
+  Monitor DNS traffic using Pcap
+  $ stella watch -C dns
+	
+  Monitor HTTP traffic using Pcap
+  $ stella watch -C http
+	
+  Monitor HTTP traffic using a proxy (don't forget to configure your browser)
+  $ stella watch -P
+
+
+h3. Sample Output
+
+<pre><code>
+  $ stella -f csv -x 5 -w 0.75 -r 25,125 -m "httpd 2.2.9-prefork" siege -c 75 -r 10 -b http://testapp:5600/
+	Writing test data to: stella/testruns/2008-12-23/test-054
+
+	  Warmup:       3750@37/1   100%    264.29/s    0.140s    0.024MB/s    0.340MB   14.000s .
+
+	 -------------------------------------------------------------------
+	                 REQ@VU/s  AVAIL       REQ/s     RTIME       DATA/s       DATA      TIME
+
+	  Run 01:       7500@75/1   100%    345.30/s    0.210s    0.032MB/s    0.690MB   21.720s
+	  Run 02:       7500@75/1   100%    360.58/s    0.200s    0.033MB/s    0.690MB   20.800s
+	  Run 03:       7500@75/1   100%    359.02/s    0.210s    0.033MB/s    0.690MB   20.890s
+	 -------------------------------------------------------------------
+	   Total:      22500@73     100%    354.97/s    0.207s    0.033MB/s    2.070MB   63.410s
+	 Std Dev:                             6.86/s    0.005s    0.001MB/s               0.414s
+
+	  Run 04:      10000@100/1  100%    384.47/s    0.260s    0.035MB/s    0.920MB   26.010s
+	  Run 05:      10000@100/1  100%    385.06/s    0.260s    0.035MB/s    0.920MB   25.970s
+	  Run 06:      10000@100/1  100%    380.95/s    0.260s    0.035MB/s    0.920MB   26.250s
+	 -------------------------------------------------------------------
+	   Total:      30000@98     100%    383.49/s    0.260s    0.035MB/s    2.760MB   78.230s
+	 Std Dev:                             1.81/s    0.000s    0.000MB/s               0.124s
+
+	  Run 07:      12500@125/1  100%    397.20/s    0.310s    0.036MB/s    1.140MB   31.470s
+	  Run 08:      12500@125/1  100%    397.08/s    0.310s    0.036MB/s    1.140MB   31.480s
+	  Run 09:      12500@125/1  100%    397.58/s    0.310s    0.036MB/s    1.140MB   31.440s
+	 -------------------------------------------------------------------
+	   Total:      37500@123    100%    397.29/s    0.310s    0.036MB/s    3.420MB   94.390s
+	 Std Dev:                             0.21/s    0.000s    0.000MB/s               0.017s
+
+	 -------------------------------------------------------------------
+	   Total:      90000@98     100%    378.58/s    0.259s    0.035MB/s    8.250MB  236.030s
+	 Std Dev:                            18.09/s    0.042s    0.002MB/s               4.225s
+</pre></code>
+
+All test data is collected under ./stella (this can be changed with the parameter --datapath):
+
+  $ ls -l ./stella/testruns/2008-12-23/
+  test-001   test-002   test-003   test-004   test-005   test-006  ...  test-054
+  
+
+A symbolic link points to the most recent test:
+
+  $ ls -l ./stella/latest/
+  ID.txt    MESSAGE.txt  SUMMARY.csv  run01    run02    run03    run04    run05    warmup
+  
+
+Each run directory contains all associated data, including the command and configuration
+
+  $ ls -l ./stella/latest/run01/
+    COMMAND.txt    STDOUT.txt    siege.log    STDERR.txt    SUMMARY.csv    siegerc
+    
+  
+h2. Known Issues
+
+* The output for the REQ@VU/s columns is a work in progress. It's not aligned across tools and it will likely change in the next release. 
+* The summary data has not been audited. Don't trust and double verify!
+* httperf is functional but not all parameters are supported. 
+* The Ruby API has not been finalized. It's functional but there's no example because it is subject to change. 
+* There is an issue with parsing ipv6 ip addresses with Ruby-Pcap or Net-DNS. This affects only dns sniffing with pcap. Reproduce by running "stella watch -C dns" and requesting "apple.com"
+
+
+h2. Report an issue
+
+Email issues and bugs to stella@solutious.com
+
+
+h2. More Information
+
+"Stellaaahhhh":http://www.youtube.com/watch?v=wmq-JDonTpc
+
+
+h2. License
+
+See LICENSE.txt

data/Rakefile

@@ -0,0 +1,88 @@
+
+require 'rubygems'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'fileutils'
+include FileUtils
+ 
+task :default => :test
+ 
+# SPECS ===============================================================
+ 
+desc 'Run specs with unit test style output'
+task :test do |t|
+#  sh "specrb -s tests/*_test.rb"
+  sh "specrb -s tests/*_test.rb"
+end
+
+# PACKAGE =============================================================
+
+
+STELLA_HOME = File.expand_path(File.join(File.dirname(__FILE__)))
+$: << File.join(STELLA_HOME, 'lib')
+
+require 'stella'
+version = Stella::VERSION.to_s
+name = "stella"
+
+spec = Gem::Specification.new do |s|
+	s.name = name
+	s.version = version
+	s.summary = "Your friend in performance testing."
+	s.description = "Run Apache Bench, Siege, or httperf tests in batches and aggregate results."
+	s.author = "Delano Mandelbaum"
+	s.email = "delano@solutious.com"
+	s.homepage = "http://stella.solutious.com/"
+	s.executables = [ "stella", "stella.bat" ]
+	s.rubyforge_project = "stella"
+  s.extra_rdoc_files  = ['README.textile']
+  
+  # NOTE: how to make optional dependencies?
+	s.add_dependency 'mongrel'
+	s.add_dependency 'rspec'
+	s.add_dependency 'net-dns'
+
+	s.platform = Gem::Platform::RUBY
+	s.has_rdoc = true
+	
+	s.files = %w(Rakefile) + Dir.glob("{bin,doc,lib,tests,support,vendor}/**/**/*")
+	
+	s.require_path = "lib"
+	s.bindir = "bin"
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+	p.need_tar = true if RUBY_PLATFORM !~ /mswin/
+end
+
+
+
+task :install => [ :rdoc, :package ] do
+	sh %{sudo gem install pkg/#{name}-#{version}.gem}
+end
+
+task :uninstall => [ :clean ] do
+	sh %{sudo gem uninstall #{name}}
+end
+
+
+
+Rake::RDocTask.new do |t|
+	t.rdoc_dir = 'doc'
+	t.title    = "stella, a friend in performance testing"
+	t.options << '--line-numbers' << '--inline-source' << '-A cattr_accessor=object'
+	t.options << '--charset' << 'utf-8'
+	t.rdoc_files.include('LICENSE.txt')
+	t.rdoc_files.include('README.textile')
+	t.rdoc_files.include('CHANGES.txt')
+	t.rdoc_files.include('lib/utils/*.rb')
+	t.rdoc_files.include('lib/stella.rb')
+	t.rdoc_files.include('lib/stella/*.rb')
+	t.rdoc_files.include('lib/stella/**/*.rb')
+end
+
+CLEAN.include [ 'pkg', '*.gem', '.config', 'doc' ]
+
+
+

data/bin/stella

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby 
+
+STELLA_HOME = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+$:.unshift(File.join(STELLA_HOME, 'lib')) # Make sure our local lib is first in line
+
+require 'stella'
+require 'stella/cli'
+
+## Create and run the application
+app = Stella::CLI.new(ARGV, STDIN)
+app.run
+

data/bin/stella.bat

@@ -0,0 +1,12 @@
+@echo off
+
+rem Check for funkiness when called from another batch script.
+rem We want FULL_PATH to contain the full path to the stella bin directory. 
+IF EXIST "%~dp0stella.bat" (set FULL_PATH=%~dp0) ELSE (set FULL_PATH=%~dp$PATH:0)
+
+rem Check for JRuby, otherwise use Ruby.
+rem We want EXECUTABLE to contain either "jruby" or "ruby"
+IF EXIST "%JRUBY_HOME%" (set EXECUTABLE=jruby) ELSE (set EXECUTABLE=ruby)
+
+rem Call the Ruby script, passing it all the arguments.
+@%EXECUTABLE% %FULL_PATH%stella %*

data/lib/daemonize.rb

@@ -0,0 +1,56 @@
+module Daemonize
+  VERSION = "0.1.2"
+
+  # Try to fork if at all possible retrying every 5 sec if the
+  # maximum process limit for the system has been reached
+  def safefork
+    tryagain = true
+
+    while tryagain
+      tryagain = false
+      begin
+        if pid = fork
+          return pid
+        end
+      rescue Errno::EWOULDBLOCK
+        sleep 5
+        tryagain = true
+      end
+    end
+  end
+
+  # This method causes the current running process to become a daemon
+  # If closefd is true, all existing file descriptors are closed
+  def daemonize(oldmode=0, closefd=false)
+    srand # Split rand streams between spawning and daemonized process
+    safefork and exit # Fork and exit from the parent
+
+    # Detach from the controlling terminal
+    unless sess_id = Process.setsid
+      raise 'Cannot detach from controlled terminal'
+    end
+
+    # Prevent the possibility of acquiring a controlling terminal
+    if oldmode.zero?
+      trap 'SIGHUP', 'IGNORE'
+      exit if pid = safefork
+    end
+
+    Dir.chdir "/"   # Release old working directory
+    File.umask 0000 # Insure sensible umask
+
+    if closefd
+      # Make sure all file descriptors are closed
+      ObjectSpace.each_object(IO) do |io|
+        unless [STDIN, STDOUT, STDERR].include?(io)
+          io.close rescue nil
+        end
+      end
+    end
+
+    STDIN.reopen "/dev/null"       # Free file descriptors and
+    STDOUT.reopen "/dev/null", "a" # point them somewhere sensible
+    STDERR.reopen STDOUT           # STDOUT/STDERR should go to a logfile
+    return oldmode ? sess_id : 0   # Return value is mostly irrelevant
+  end
+end

data/lib/pcaplet.rb

@@ -0,0 +1,180 @@
+require 'pcap'
+
+
+# Pcaplet
+#
+# Adapted from Ruby portion of Ruby-Pcap:
+# http://www.goto.info.waseda.ac.jp/~fukusima/ruby/pcap-e.html
+# The lib/pcaplet.rb and lib/pcap_misc.rb files are in merge into this file
+# and cleaned up. The Ruby-Pcap C extension was modified to apply several fixes
+# so it would compile on OS X and to remove several warning messages. With 
+# help from: http://d.hatena.ne.jp/takuma104/20080210/1202638583  
+# We specifically removed the dependency on ARGV and OptParse. It was messy
+# and required ARGV to be specifically modified before requiring this package. 
+# Manual: http://www.goto.info.waseda.ac.jp/~fukusima/ruby/pcap/doc/index.html
+class Pcaplet
+
+  attr_accessor :debug, :verbose
+    # do not convert address to name
+  attr_accessor :convert
+  attr_accessor :device, :rfile, :count, :snaplen, :filter
+
+  def initialize(args = {})
+  
+    @debug   = args[:debug]   || false
+    @verbose = args[:verbose] || false
+    @device = args[:device] || guess_device
+    @rfile = args[:rfile]
+    @convert = args[:convert] || false
+    @count   = args[:count].to_i || 1000
+    @snaplen = args[:snaplen].to_i > 0 ? args[:snaplen] : 1500
+    @filter = args[:filter] || ''
+  
+    Pcap.convert = @convert
+    
+    # check option consistency
+    usage(1) if @device && @rfile
+    if !@device and !@rfile
+      @device = Pcap.lookupdev
+    end
+
+    # open
+    begin
+      if @device
+        @capture = Pcap::Capture.open_live(@device, @snaplen)
+      elsif @rfile
+        if @rfile !~ /\.gz$/
+          @capture = Capture.open_offline(@rfile)
+        else
+          $stdin = IO.popen("gzip -dc < #@rfile", 'r')
+          @capture = Capture.open_offline('-')
+        end
+      end
+      @capture.setfilter(@filter) if @filter
+      rescue Pcap::PcapError, ArgumentError
+        $stdout.flush
+        $stderr.puts $!
+        exit(1)
+      end
+    end
+
+  attr('capture')
+
+
+  def add_filter(f)
+    if @filter == nil || @filter =~ /^\s*$/  # if empty
+      #puts "filter is nil or empty"
+      @filter = f
+    else
+      #puts "filter is #{@filter}"
+      f = f.source if f.is_a? Filter
+      @filter = "( #{@filter} ) and ( #{f} )"
+    end
+    #puts "filter being set #{@filter}"
+    @capture.setfilter(@filter)
+  end
+
+  def each_packet(&block)
+    
+    begin
+      duplicated = (RUBY_PLATFORM =~ /linux/ && @device == "lo")
+      unless duplicated
+        @capture.loop(@count, &block)
+      else
+        flip = true
+        @capture.loop(@count) do |pkt|
+          flip = (! flip)
+          next if flip
+          block.call pkt
+        end
+      end
+    end
+  end
+
+  alias each each_packet
+
+  def close
+    @capture.close
+  end
+end
+
+
+
+module Pcap
+  class Packet
+    def to_s
+      'Some packet'
+    end
+
+    def inspect
+      "#<#{type}: #{self}>"
+    end
+  end
+
+  class IPPacket
+    def to_s
+      "#{ip_src} > #{ip_dst}"
+    end
+  end
+
+  class TCPPacket
+    def tcp_data_len
+      ip_len - 4 * (ip_hlen + tcp_hlen)
+    end
+    
+    # The 3-way handshake that initiates a request
+    # ....S. --->
+    # .A..S. <---
+    # .A.... --->
+    #
+    # The teardown procedure at the end of the request
+    # .A...F --->
+    # .A.... <---
+    # .A...F --->
+    # .A.... <...
+    def tcp_flags_s
+      return \
+	      (tcp_urg? ? 'U' : '.') +  # Urgent
+	      (tcp_ack? ? 'A' : '.') +  # ACKnowledgement: Successful transfer
+	      (tcp_psh? ? 'P' : '.') +  # Push
+	      (tcp_rst? ? 'R' : '.') +  # Reset
+	      (tcp_syn? ? 'S' : '.') +  # SYNchronization: this is the first segment in a new transaction
+        (tcp_fin? ? 'F' : '.')    # FINal: final transaction
+    end
+
+    def to_s
+      "#{src}:#{sport} > #{dst}:#{dport} #{tcp_flags_s}"
+    end
+  end
+
+  class UDPPacket
+    def to_s
+      "#{src}:#{sport} > #{dst}:#{dport} len #{udp_len} sum #{udp_sum}"
+    end
+  end
+
+  class ICMPPacket
+    def to_s
+      "#{src} > #{dst}: icmp: #{icmp_typestr}"
+    end
+  end
+
+  #
+  # Backword compatibility
+  #
+  IpPacket = IPPacket unless defined? IpPacket
+  IpAddress = IPAddress unless defined? IpAddress
+  TcpPacket = TCPPacket unless defined? TcpPacket
+  UdpPacket = UDPPacket unless defined? UdpPacket
+
+end
+
+class Time
+  # tcpdump style format
+  def tcpdump
+    sprintf "%0.2d:%0.2d:%0.2d.%0.6d", hour, min, sec, tv_usec
+  end
+end
+
+
+