stella 0.5.4 → 0.5.5

data/README.textile

@@ -1,9 +1,13 @@
 h1. Stella - Your Performance Testing Friend
 
-Release: 0.5.4-alpha (2009-01-07)
+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
 
@@ -17,9 +21,10 @@ h2. Prerequisites
 ** Ruby-Pcap (optional, for packet sniffing)
 
 * One of:
-** "Apache Bench":http://httpd.apache.org/docs/2.0/programs/ab.html
+** "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
@@ -59,14 +64,14 @@ On Ruby, 1.8.6, Ruby-Pcap produces the following warnings at runtime: "pcap.bund
 
 h2. Usage Examples
 
-  Run Apache Bench with a warmup and rampup from 100 to 300 virtual users in increments of 25
-  $ stella --warmup=0.5 --rampup=25,300 ab -c 100 -n 10000 http://stellaaahhhh.com/search?term=trooper
+  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 100 -r 100 -b http://stellaaahhhh.com/search?term=flock+of+seagulls
+  $ 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=3000 --timeout=5
+  $ 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
@@ -81,7 +86,7 @@ h2. Usage Examples
 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://stella:5600/
+  $ 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 .
@@ -137,10 +142,9 @@ 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 needs a lot more testing (most dev was done with ab and siege).
+* 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 are no specs. 
-* 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 -P dns" and requesting "apple.com"
+* 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

data/Rakefile

@@ -1,42 +1,29 @@
-require 'rake'
-require 'spec/rake/spectask'
 
-desc "Run all specs"
-Spec::Rake::SpecTask.new('spec') do |t|
-	t.spec_files = FileList['spec/*_spec.rb']
-end
-
-desc "Print specdocs"
-Spec::Rake::SpecTask.new(:doc) do |t|
-	t.spec_opts = ["--format", "specdoc", "--dry-run"]
-	t.spec_files = FileList['spec/*_spec.rb']
-end
-
-desc "Run all examples with RCov"
-Spec::Rake::SpecTask.new('rcov') do |t|
-	t.spec_files = FileList['spec/*_spec.rb']
-	t.rcov = true
-	t.rcov_opts = ['--exclude', 'examples']
-end
-
-task :default => :spec
-
-######################################################
-
-require 'rake'
-require 'rake/testtask'
+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|
@@ -52,15 +39,14 @@ spec = Gem::Specification.new do |s|
   s.extra_rdoc_files  = ['README.textile']
   
   # NOTE: how to make optional dependencies?
-	#s.add_dependency 'mongrel'
+	s.add_dependency 'mongrel'
 	s.add_dependency 'rspec'
 	s.add_dependency 'net-dns'
-	#s.add_dependency 'session'
 
 	s.platform = Gem::Platform::RUBY
 	s.has_rdoc = true
 	
-	s.files = %w(Rakefile) + Dir.glob("{bin,doc,lib,spec,support,vendor}/**/**/*")
+	s.files = %w(Rakefile) + Dir.glob("{bin,doc,lib,tests,support,vendor}/**/**/*")
 	
 	s.require_path = "lib"
 	s.bindir = "bin"
@@ -71,6 +57,7 @@ Rake::GemPackageTask.new(spec) do |p|
 end
 
 
+
 task :install => [ :rdoc, :package ] do
 	sh %{sudo gem install pkg/#{name}-#{version}.gem}
 end
@@ -79,11 +66,7 @@ task :uninstall => [ :clean ] do
 	sh %{sudo gem uninstall #{name}}
 end
 
-Rake::TestTask.new do |t|
-	t.libs << "spec"
-	t.test_files = FileList['spec/*_spec.rb']
-	t.verbose = true
-end
+
 
 Rake::RDocTask.new do |t|
 	t.rdoc_dir = 'doc'
@@ -91,7 +74,8 @@ Rake::RDocTask.new do |t|
 	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.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')
@@ -100,3 +84,5 @@ end
 
 CLEAN.include [ 'pkg', '*.gem', '.config', 'doc' ]
 
+
+

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/stella/adapter/ab.rb

@@ -1,5 +1,5 @@
 
-
+require 'fileutils'
 
 module Stella
   module Adapter
@@ -45,12 +45,14 @@ module Stella
       attr_accessor :C, :H, :A, :P, :X, :V, :k, :d, :S, :e, :g, :r, :h, :Z, :f
       
       def initialize(options={}, arguments=[])
-        super(options, arguments)
         @private_variables = ['private_variables', 'name', 'arguments', 'load_factor', 'working_directory']
         @c = 1
         @n = 1
         @name = 'ab'
         @load_factor = 1
+        
+        super(options, arguments)
+        
       end
       
       def error
@@ -65,14 +67,17 @@ module Stella
         vsn
       end
       
+      def percentiles_file
+        @working_directory + "/ab-percentiles.log" 
+      end
+      
+      def requests_file
+        @working_directory + "/ab-requests.log" 
+      end
+      
       def before
-        
-        @e = @working_directory + "/ab-percentiles.log" 
-        @e = File.expand_path(@e)
-
-        @g = @working_directory + "/ab-requests.log" 
-        @g = File.expand_path(@g)
-
+        @e = percentiles_file if @e.nil?
+        @g = requests_file if @g.nil?
       end
       
       def command
@@ -83,12 +88,12 @@ module Stella
         instance_variables.each do |name|
           canon = name.to_s.tr('@', '')        # instance_variables returns '@name'
           next if @private_variables.member?(canon)
-
+          
           # It's important that we take the value from the getter method
           # because it applies the load factor. 
           value = self.send(canon)
           if (value.is_a? Array)
-            value.each { |el| command << "-#{canon} #{EscapeUtil.shell_single_word(el.to_s)} " }
+            value.each { |el| command << "-#{canon} #{EscapeUtil.shell_single_word(value.to_s)} " }
           else
             command << "-#{canon} #{EscapeUtil.shell_single_word(value.to_s)} "
           end
@@ -96,6 +101,7 @@ module Stella
         end
 
         command << (@arguments.map { |uri| "#{uri}" }).join(' ') unless @arguments.empty?
+        
         command
       end
       # loadtest
@@ -111,32 +117,34 @@ module Stella
       end
       
       
-      def process_options(arguments)
-        options = OpenStruct.new
+      def process_arguments(arguments)
         opts = OptionParser.new 
         
+        # TODO: there's no need to use an OpenStruct here. It's confusing b/c we can 
+        # use the instance var methods here instead of in Base::options=.
+        
         # TODO: Print a note for w that we don't parse the HTML results
         %w{v w i V k d S r h}.each do |n|
-          opts.on("-#{n}") do |v| options.send("#{n}=", true) end
+          opts.on("-#{n}") do |v| instance_variable_set("@#{n}", true) end
         end
         
         %w{e g p T x y z P Z f A}.each do |n|
-          opts.on("-#{n} S", String) do |v| options.send("#{n}=", v)  end
+          opts.on("-#{n} S", String) do |v| instance_variable_set("@#{n}", v)  end
         end
         
         %w{c n t b}.each do |n|
-          opts.on("-#{n} S", Integer) do |v| options.send("#{n}=", v) end
+          opts.on("-#{n} S", Integer) do |v| instance_variable_set("@#{n}", v) end
         end
         
-        opts.on('-H S', String) do |v| options.H ||= []; options.H << v; end
-        opts.on('-C S', String) do |v| options.C ||= []; options.C << v; end
+        opts.on('-H S', String) do |v| @H ||= []; @H << v; end
+        opts.on('-C S', String) do |v| @C ||= []; @C << v; end
         
         opts.on('-b') do |v| 
-          Stella::LOGGER.warn("-b is not an ab option. I'll pretend it's not there.")
+          Stella.warn("-b is not an ab option. I'll pretend it's not there.")
         end
         
         opts.on('-r N',Integer) do |v| 
-          Stella::LOGGER.error("-r is not an ab parameter. You probably want -n.")
+          Stella.error("-r is not an ab parameter. You probably want -n.")
           exit 1
         end
         
@@ -145,10 +153,10 @@ module Stella
         opts.parse!(arguments)
         
         if arguments.empty?
-          Stella::LOGGER.error("You need to provide a URI")
+          Stella.error("You need to provide a URI")
           exit 1
         elsif arguments.size > 1
-          Stella::LOGGER.warn("ab can handle only one URI. The others will be ignored.")
+          Stella.warn("ab can handle only one URI. The others will be ignored.")
           arguments = arguments.first
         else
           # Let's make sure the URI has a path (at least a trailing slash). Otherwise
@@ -156,17 +164,17 @@ module Stella
           begin
             uri = URI.parse(arguments.first)
             if !uri || uri.path.empty?
-              Stella::LOGGER.error("ab requires a trailing slash for #{uri.to_s}") 
+              Stella.error("ab requires a trailing slash for #{uri.to_s}") 
               exit 1
             end
           rescue => ex
-            Stella::LOGGER.error("Bad URI: #{arguments.first}") 
+            Stella.error("Bad URI: #{arguments.first}") 
             exit 1
           end
         end
         
+        self.arguments = arguments
         
-        options
       rescue OptionParser::InvalidOption => ex
         # We want to replace this text so we grab just the name of the argument
         badarg = ex.message.gsub('invalid option: ', '')
@@ -176,17 +184,19 @@ module Stella
       def after
         # We want to maintain copies of all test output, even when the user has 
         # supplied other path names so we'll copy the files from the testrun directory
-        # to the location specified by the user
-        [[@options.e, 'csv'], [@options.g, 'tsv']].each do |tuple|
-          if File.expand_path(File.dirname(tuple[0])) != File.expand_path(@runpath)
+        # to the location specified by the user.
+        # NOTE: For tests with more than one test run, the specified files will be 
+        # overwritten after each run. Should we force append the run number? 
+        [[@e, 'percentiles'], [@g, 'requests']].each do |tuple|
+          if File.expand_path(File.dirname(tuple[0])) != File.expand_path(@working_directory)
             from = tuple[0]
-            to = @runpath + "/ab-#{tuple[1]}.log"
+            to = @working_directory + "/ab-#{tuple[1]}.log"
             next unless File.exists?(from)
-            File.copy(from, to)
+            FileUtils.cp(from, to)
           end
         end
 
-        save_stats
+        
       end
 
 
@@ -257,14 +267,14 @@ module Stella
 
       
       # Apache bench writes the summary to STDOUT
-      def stats_file
+      def summary_file
         File.new(stdout_path) if File.exists?(stdout_path)
       end
 
-      def stats
-        return unless stats_file
+      def summary
+        return unless summary_file
         raw = {}
-        stats_file.each_line { |l|
+        summary_file.each_line { |l|
           l.chomp!
           nvpair = l.split(':')
           next unless nvpair && nvpair.size == 2
@@ -292,8 +302,8 @@ module Stella
         # Transfer rate:          84.90 [Kbytes/sec] received
 
         stats = Stella::Test::Run::Summary.new
-
-        unless raw.empty? || !raw.has_key?(:time_taken_for_tests)
+        
+        if !raw.empty? && raw.has_key?(:time_taken_for_tests)
 
           stats.elapsed_time = raw[:time_taken_for_tests]
 
@@ -312,10 +322,10 @@ module Stella
           stats.failed = raw[:failed_requests].to_i
 
           stats.transactions = stats.successful + stats.failed
-
+          
           #stats.raw = raw  if @global_options.debug
         end
-
+        
         stats
       end
 

data/lib/stella/adapter/base.rb

@@ -10,12 +10,16 @@ module Stella::Adapter
   class Base
     
     
-    attr_accessor :working_directory, :stats
+    attr_accessor :working_directory
     attr_reader :load_factor, :arguments
     
     def initialize(options={}, arguments=[])
-      self.arguments = arguments
-      self.options = options
+      if options.is_a? Array
+        self.process_arguments(options) 
+      else
+        self.options = options
+        self.arguments = arguments 
+      end
     end
     
     def load_factor=(load_factor)
@@ -33,22 +37,23 @@ module Stella::Adapter
       File.join(@working_directory, "SUMMARY.#{ext}")
     end
     
-    # process_options
+    # process_arguments
     #
     # This method must be overridden by the implementing class. This is intended
     # for processing the command-specific command-line arguments
-    # TODO: Rename to process_arguments
-    def process_options
+    def process_arguments
       raise Stella::TEXT.msg(:error_class_must_override, 'process_options')
     end
     
     # options=
     #
-    # Takes a hash or OpenStruct and applies the values to the instance variables. 
+    # Takes a hash, OpenStruct and applies the values to the instance variables. 
     # The keys should conincide with with the command line argument names. 
+    # by process_options first and 
     # i.e. The key for --help should be :help 
     def options=(options={})
       options = options.marshal_dump if options.is_a? OpenStruct
+      
       unless options.nil? || options.empty?
         options.each_pair do |name,value|
           next if @private_variables.member?(name)
@@ -71,7 +76,7 @@ module Stella::Adapter
     end
     
     def rate
-      1
+      @rate || 0
     end
     def vuser_rate
       "#{vusers}/#{rate}"
@@ -81,6 +86,10 @@ module Stella::Adapter
       raise Stella::TEXT.msg(:error_class_must_override, 'command')
     end
     
+    def summary
+      raise Stella::TEXT.msg(:error_class_must_override, 'summary')
+    end
+    
     def add_header
       raise Stella::TEXT.msg(:error_class_must_override, 'add_header')
     end

data/lib/stella/adapter/httperf.rb

@@ -29,11 +29,12 @@ module Stella
       attr_writer :version, :add_header, :wlog, :wsess, :wsesslog, :wset
       
       def initialize(options={}, arguments=[])
-        super(options, arguments)
-        @name = 'httperf'
         
+        @name = 'httperf'
         @private_variables = ['private_variables', 'name', 'arguments', 'load_factor', 'working_directory']
         @load_factor = 1
+        
+        super(options, arguments)
       end
       
       
@@ -75,13 +76,10 @@ module Stella
       def after
 
 
-        save_stats
       end
 
-      #httperf --hog --server=queen --uri=/0k.html --num-conns=10000 --rate=0 --timeout=30 --think-timeout=0
-      def process_options(arguments)
+      def process_arguments(arguments)
         
-        options = OpenStruct.new
         opts = OptionParser.new 
         opts.on('--hog') do @hog = true end
         opts.on('--server=S', String) do |v| @server = v end
@@ -126,17 +124,21 @@ module Stella
         
         
         opts.on('--wlog=S', String) do |v| @wlog = Stella::Util::expand_str(v) end
-        opts.on('--wsess=S', String) do |v| @wsess = Stella::Util::expand_str(v) end
+        opts.on('--wsess=S', String) do |v| @wsess = Stella::Util::expand_str(v, Integer) end
         opts.on('--wsesslog=S', String) do |v| @wsesslog = Stella::Util::expand_str(v) end
         opts.on('--wset=S', String) do |v| @wset = Stella::Util::expand_str(v) end
+        
+        if @wsess
           
+        end
+        
         # parse! removes the options it finds.
         # It also fails when it finds unknown switches (i.e. -X)
         # Which should leave only the remaining arguments (URIs in this case)
         opts.parse!(arguments)
-
         
-        options
+        self.arguments = arguments
+        
       rescue OptionParser::InvalidOption => ex
         # We want to replace this text so we grab just the name of the argument
         badarg = ex.message.gsub('invalid option: ', '')
@@ -181,13 +183,17 @@ module Stella
         end
       end
       def vusers
-         @rate
+         @wsess[1]
       end
+      def vuser_rate
+        "#{vusers}/#{rate}"
+      end
+      
       def vusers=(v)
         0
       end
       def requests
-        @num_conns # TODO: also check wsess and wlog params
+        @num_conns || (@wsess[0] * @wsess[1])
       end
       def requests=(v)
         0
@@ -224,7 +230,7 @@ module Stella
       
 
       # Siege writes the summary to STDERR
-      def stats_file
+      def summary_file
         File.new(stdout_path) if File.exists?(stdout_path)
       end
       
@@ -265,10 +271,10 @@ module Stella
       # Errors: total 0 client-timo 0 socket-timo 0 connrefused 0 connreset 0
       # Errors: fd-unavail 0 addrunavail 0 ftab-full 0 other 0
       
-      def stats
-        return unless stats_file
+      def summary
+        return unless summary_file
         
-        raw = stats_file.readlines.join
+        raw = summary_file.readlines.join
         stats = Stella::Test::Run::Summary.new
         
         raw.scan(/Request rate: (\d+?\.\d+?) req.s .(\d+?\.\d+?) ms.req./) do |rate,time|
@@ -283,12 +289,12 @@ module Stella
           stats.transactions = conn.to_i
         end
         
-        raw.scan(/Reply size [B]: header (\d+\.\d+?) content (\d+\.\d+?) footer (\d+\.\d+?) .total (\d+\.\d+?)./) do |h,c,f,t|
-          stats.data_transferred = ((t.to_f || 0 ) / 1_048_576).to_f # TODO: convert from bytes to MB
+        raw.scan(/header (\d+\.\d+?)\s+.+?\s+.total (\d+\.\d+?)./) do |h,t|
+          stats.data_transferred = ((t.to_f || 0 ) / 1_048_576).to_f
+          stats.headers_transferred = ((h.to_f || 0 ) / 1_048_576).to_f
         end
         stats.vusers = self.vusers
         
-        
         stats
       end
 

data/lib/stella/adapter/pcap_watcher.rb

@@ -61,7 +61,7 @@ module Stella
         @sport = options[:port] || @dport
         
         @device = options[:device] || guess_device
-        @snaplen = options[:snaplen] || 1500         # 10KB
+        @snaplen = options[:snaplen] || 10000         # 10KB
         @maxpacks = options[:maxpacks] || 100_000
         
         Stella::LOGGER.info("Watching interface #{@device} for #{@service} activity on #{@protocol} port #{@dport}")