elbping 0.0.10 → 0.0.11

data/lib/elbping/cli.rb

@@ -6,13 +6,16 @@ require 'uri'
 require 'elbping/pinger.rb'
 require 'elbping/resolver.rb'
 require 'elbping/display.rb'
+require 'elbping/stats.rb'
 
 module ElbPing
+  # Setup and initialization for running as a CLI app happens here. Specifically, on load it will
+  # read in environment variables and set up default values for the app.
   module CLI
 
     # Set up default options
     OPTIONS = {}
-    OPTIONS[:verb_len]      = ENV['PING_ELB_MAXVERBLEN']    || 128
+    OPTIONS[:verb_len]      = ENV['PING_ELB_VERBLEN']       || 128
     OPTIONS[:nameserver]    = ENV['PING_ELB_NS']            || 'ns-941.amazon.com'
     OPTIONS[:count]         = ENV['PING_ELB_PINGCOUNT']     || 0
     OPTIONS[:timeout]       = ENV['PING_ELB_TIMEOUT']       || 10
@@ -44,81 +47,91 @@ module ElbPing
       end
     end
 
-    # Parse options
+    # Displays usage
     def self.usage
-      puts PARSER.help
+      ElbPing::Display.out PARSER.help
       exit(false)
     end
 
-    # Main entry point of the program
-    def self.main
-      PARSER.parse!(ARGV) rescue usage
-      run = true
-
-      # Set up summary objects
-      total_summary = {
-        :reqs_attempted =>  0,
-        :reqs_completed =>  0,
-        :latencies      => [],
-      }
-      node_summary = {}
+    # Main entry point of the program. Specifically, this method will:
+    #
+    # * Parse and validate command line arguments
+    # * Use the `ElbPing::Resolver` to discover ELB nodes
+    # * Use the `ElbPing::HttpPinger` to ping ELB nodes
+    # * Track the statistics for these pings
+    # * And, finally, use call upon `ElbPing::Display` methods to output to stdout
 
+    def self.main
       # Catch ctrl-c
+      run = true
       trap("SIGINT") {
         run = false
       }
 
+      ##
+      # Parse and validate command line arguments
+      PARSER.parse!(ARGV) rescue usage
+
       if ARGV.size < 1
         usage
       end
+
       unless ARGV[0] =~ URI::regexp
-        puts "ERROR: ELB URI does not seem valid"
+        ElbPing::Display.error "ELB URI does not seem valid"
         usage
       end
+
       elb_uri_s = ARGV[0]
       elb_uri = URI.parse(elb_uri_s)
 
+      ##
+      # Discover ELB nodes
+      #
+      # TODO: Perhaps some retry logic
+      nameserver = OPTIONS[:nameserver]
       begin
-        nodes = ElbPing::Resolver.find_elb_nodes(elb_uri.host,
-          OPTIONS[:nameserver])
+        nodes = ElbPing::Resolver.find_elb_nodes elb_uri.host, nameserver
       rescue
-        puts "Error querying DNS for #{elb_uri.host} (NS: #{OPTIONS[:nameserver]})"
+        ElbPing::Display.error "Unable to query DNS for #{elb_uri.host} using #{nameserver}"
         exit(false)
       end
 
       if nodes.size < 1
-        puts "Could not find any ELB nodes, no pings sent."
+        ElbPing::Display.error "Could not find any ELB nodes, no pings sent"
         exit(false)
       end
 
-      nodes.each { |node| node_summary[node] = total_summary.clone }
+      ##
+      # Set up summary objects for stats tracking of latency and loss
+      stats = ElbPing::Stats.new
+      nodes.each { |node| stats.add_node node }
 
+      ##
+      # Run the main loop of the program
       iteration = 0
-      while (OPTIONS[:count] < 1 || iteration < OPTIONS[:count]) && run
+      while run && (OPTIONS[:count] < 1 || iteration < OPTIONS[:count])
+
         sleep OPTIONS[:wait] if iteration > 0
 
+        ##
+        # Ping each node while tracking requests, responses, and latencies
         nodes.map { |node|
-          total_summary[:reqs_attempted] += 1
-          node_summary[node][:reqs_attempted] += 1
-
           status = ElbPing::HttpPinger.ping_node(node,
             elb_uri.port,
             (elb_uri.path == "") ? "/" : elb_uri.path,
             (elb_uri.scheme == 'https'),
             OPTIONS[:verb_len], OPTIONS[:timeout])
 
-          unless status[:code] == :timeout
-            total_summary[:reqs_completed] += 1
-            total_summary[:latencies] += [status[:duration]]
-            node_summary[node][:reqs_completed] += 1
-            node_summary[node][:latencies] += [status[:duration]]
-          end
+          # Display the response from the ping
+          ElbPing::Display.response status
 
-          ElbPing::Display.response(status)
+          # Register stats
+          stats.register status
         }
         iteration += 1
       end
-      ElbPing::Display.summary(total_summary, node_summary)
+      # Display the stats summary
+      ElbPing::Display.summary stats
     end
   end
 end

data/lib/elbping/display.rb

@@ -1,7 +1,35 @@
 
 module ElbPing
+  # This is responsible for all things that send to stdout. It is mostly only used by `ElbPing::CLI`
   module Display
-    # Format and display the ping data
+
+    # Print message to the screen. Mostly used in case someone ever wants to override it.
+    #
+    # Arguments:
+    # * msg: (string) Message to display
+
+    def self.out(msg)
+      puts msg
+    end
+
+    # Print error message to the screen
+    #
+    # Arguments:
+    # * msg: (string) Message to display
+
+    def self.error(msg)
+      self.out "ERROR: #{msg}"
+    end
+
+    # Format and display the ping data given a response
+    #
+    # Arguments:
+    # * status: (hash) containing:
+    #   * :node (string) IP address of node
+    #   * :code (Fixnum || string || symbol) HTTP status code or symbol representing error during ping
+    #   * :duration (Fixnum) Latency in milliseconds from ping
+    #   * :exception (string, optional) Message to display from exception
+
     def self.response(status)
       node = status[:node]
       code = status[:code]
@@ -9,45 +37,26 @@ module ElbPing
       exc = status[:exception]
       exc_display = exc ? "exception=#{exc}" : ''
 
-      puts "Response from #{node}: code=#{code.to_s} time=#{duration} ms #{exc_display}"
+      self.out "Response from #{node}: code=#{code.to_s} time=#{duration} ms #{exc_display}"
     end
 
-    # Display summary of results (in aggregate and per-node)
-    def self.summary(total_summary, node_summary)
-      requests = total_summary[:reqs_attempted]
-      responses = total_summary[:reqs_completed]
-      loss = (1 - (responses.to_f/requests)) * 100
-
-      latencies = total_summary[:latencies]
-      avg_latency = 0
-      unless latencies.size == 0
-        sum_latency = latencies.inject { |sum, el| sum + el} || 0
-        avg_latency = (sum_latency.to_f / latencies.size).to_i # ms
-      end
-
-      node_summary.each { |node, summary|
-        requests = summary[:reqs_attempted]
-        responses = summary[:reqs_completed]
-        loss = (1 - (responses.to_f/requests)) * 100
-
-        latencies = summary[:latencies]
-        avg_latency = 0
-        unless latencies.size == 0
-          sum_latency = latencies.inject { |sum, el| sum + el} || 0
-          avg_latency = (sum_latency.to_f / latencies.size).to_i # ms
-        end
-
-        puts "--- #{node} statistics ---"
-        puts "#{requests} requests, #{responses} responses, #{loss.to_i}% loss"
-        puts "min/avg/max = #{latencies.min}/#{avg_latency}/#{latencies.max} ms"
+    # Display summary of requests, responses, and latencies (for aggregate and per-node)
+    #
+    # Arguments:
+    # * stats: (ElbPing::Stats)
+
+    def self.summary(stats)
+      stats.nodes.keys.each { |node|
+        loss_pct = (stats.node_loss(node) * 100).to_i
+        self.out "--- #{node} statistics ---"
+        self.out "#{stats.nodes[node][:requests]} requests, #{stats.nodes[node][:responses]} responses, #{loss_pct}% loss"
+        self.out "min/avg/max = #{stats.nodes[node][:latencies].min}/#{stats.nodes[node][:latencies].mean}/#{stats.nodes[node][:latencies].max} ms"
       }
 
-      puts '--- total statistics ---'
-      puts "#{requests} requests, #{responses} responses, #{loss.to_i}% loss"
-      puts "min/avg/max = #{latencies.min}/#{avg_latency}/#{latencies.max} ms"
-
+      loss_pct = (stats.total_loss * 100).to_i
+      self.out '--- total statistics ---'
+      self.out "#{stats.total[:requests]} requests, #{stats.total[:responses]} responses, #{loss_pct}% loss"
+      self.out "min/avg/max = #{stats.total[:latencies].min}/#{stats.total[:latencies].mean}/#{stats.total[:latencies].max} ms"
     end
-
   end
 end
-

data/lib/elbping/pinger.rb

@@ -3,9 +3,21 @@ require "net/http"
 require "net/https"
 
 module ElbPing
+  # Responsible for all HTTP ping-like functionality
   module HttpPinger
-    # Make HTTP request to given node using custom request method
+
+    # Make HTTP request to given node using custom request method and measure response time
+    #
+    # Arguments:
+    # * node: (string) of node IP
+    # * port: (string || Fixnum) of positive integer [1, 65535]
+    # * path: (string) of path to request, e.g. "/"
+    # * use_ssl: (boolean) Whether or not this is HTTPS
+    # * verb_len: (Fixnum) of positive integer, how long the custom HTTP verb should be
+    # * timeout: (Fixnum) of positive integer, how many _seconds_ for connect and read timeouts
+
     def self.ping_node(node, port, path, use_ssl, verb_len, timeout)
+      ##
       # Build request class
       ping_request = Class.new(Net::HTTPRequest) do
         const_set :METHOD, "A" * verb_len
@@ -13,6 +25,7 @@ module ElbPing
         const_set :RESPONSE_HAS_BODY, false
       end
 
+      ##
       # Configure http object
       start = Time.now.getutc
       http = Net::HTTP.new(node, port.to_s)
@@ -20,12 +33,15 @@ module ElbPing
       http.read_timeout     = timeout
       http.continue_timeout = timeout
 
+      # Enable SSL if it's to be used
       if use_ssl
         http.use_ssl          = true
         http.verify_mode      = OpenSSL::SSL::VERIFY_NONE
         http.ssl_timeout      = timeout
       end
 
+      ##
+      # Make the HTTP request and handle any errors along the way
       error = nil
       exc = nil
       begin

data/lib/elbping/resolver.rb

@@ -1,8 +1,11 @@
 
 require 'resolv'
 
+# A TCP-only resolver built from `Resolv::DNS`. See the docs for what it's about.
+# http://ruby-doc.org/stdlib-1.9.3/libdoc/resolv/rdoc/Resolv/DNS.html
 class TcpDNS < Resolv::DNS
-  # This is largely a copy-paste job from mri/source/lib/resolv.rb
+  # Override fetch_resource to use a TCP requester instead of a UDP requester. This
+  # is mostly borrowed from `lib/resolv.rb` with the UDP->TCP fallback logic removed.
   def fetch_resource(name, typeclass)
     lazy_initialize
     request = make_tcp_requester
@@ -19,19 +22,7 @@ class TcpDNS < Resolv::DNS
         reply, reply_name = requester.request(sender, tout)
         case reply.rcode
         when RCode::NoError
-          if reply.tc == 1 and not Requester::TCP === requester
-            requester.close
-            # Retry via TCP:
-            requester = make_tcp_requester(nameserver, port)
-            senders = {}
-            # This will use TCP for all remaining candidates (assuming the
-            # current candidate does not already respond successfully via
-            # TCP).  This makes sense because we already know the full
-            # response will not fit in an untruncated UDP packet.
-            redo
-          else
-            yield(reply, reply_name)
-          end
+          yield(reply, reply_name)
           return
         when RCode::NXDomain
           raise Config::NXDomain.new(reply_name.to_s)
@@ -46,22 +37,25 @@ class TcpDNS < Resolv::DNS
 end
 
 module ElbPing
+  # Handles all DNS resolution and, more specifically, ELB node discovery
   module Resolver
-    def self.resolve_ns(nameserver)
-      # Leftover from a resolver lib that wouldn't resolve its own nameservers
-      return [nameserver]
-    end
 
     # Resolve an ELB address to a list of node IPs. Should always return a list
     # as long as the server responded, even if it's empty.
-    def self.find_elb_nodes(target, nameserver, timeout=5)
-      # `timeout` is in seconds
-      ns_addrs = resolve_ns nameserver
+    #
+    # Arguments:
+    #   target: (string)
+    #   nameservers: (array) of strings
+    #   timeout: (fixnum)
+    #
+    # Could raise:
+    # * Timeout::Error
+    # * ?
 
-      # Now resolve our ELB nodes
+    def self.find_elb_nodes(target, nameservers, timeout=5)
       resp = nil
       Timeout::timeout(timeout) do 
-        TcpDNS.open :nameserver => ns_addrs, :search => '', :ndots => 1 do |dns|
+        TcpDNS.open :nameserver => nameservers, :search => '', :ndots => 1 do |dns|
           # TODO: Exceptions
           resp = dns.getresources target, Resolv::DNS::Resource::IN::A
         end
@@ -70,4 +64,3 @@ module ElbPing
     end
   end
 end
-

data/lib/elbping/stats.rb

@@ -0,0 +1,105 @@
+
+# TODO: Needs unit tests
+
+# An array for doing some basic stats on latencies (currently only mean)
+class LatencyBucket < Array
+  def sum
+    self.inject { |sum, el| sum + el} || 0
+  end
+
+  def mean
+    i = 0
+    unless self.size == 0
+      i = (self.sum.to_f / self.size).to_i
+    end
+  end
+end
+
+module ElbPing
+  # Tracks the statistics of requests sent, responses received (hence loss) and latency
+  class Stats
+
+    attr_reader :total, :nodes
+
+    def initialize
+      @total = {
+        :requests   =>  0,
+        :responses  =>  0,
+        :latencies  => LatencyBucket.new,
+      }
+      @nodes = {}
+    end
+
+    # Initializes stats buckets for a node if it doesn't already exist
+    #
+    # Arguments
+    # * node: (string) IP of node
+
+    def add_node(node)
+      unless @nodes.keys.include? node
+        @nodes[node] = {
+          :requests   =>  0,
+          :responses  =>  0,
+          :latencies  => LatencyBucket.new,
+        }
+      end
+    end
+
+    # Registers stats following a ping
+    #
+    # Arguments:
+    # * node: (string) IP of node
+    # * status: (hash) Status object as returned from Pinger::ping_node
+
+    def register(status)
+      node = status[:node]
+      # Register the node if it hasn't been already
+      add_node node
+
+      # Update requests sent regardless of errors
+      @total[:requests] += 1
+      @nodes[node][:requests] += 1
+
+      # Don't update response counters or latencies if we encountered an error
+      unless [:timeout, :econnrefused, :exception].include? status[:code]
+        # Increment counters
+        @total[:responses] += 1
+        @nodes[node][:responses] += 1
+
+        # Track latencies
+        @total[:latencies] << status[:duration]
+        @nodes[node][:latencies] << status[:duration]
+      end
+    end
+
+    # Calculates loss across all nodes
+    def total_loss
+      calc_loss @total[:responses], @total[:requests]
+    end
+
+    # Calculates loss for a specific node
+    #
+    # Arguments:
+    # * node: (string) IP of node
+    #
+    # TODO: Handle non-existent nodes
+
+    def node_loss(node)
+      calc_loss @nodes[node][:responses], @nodes[node][:requests]
+    end
+
+    private
+
+    # Generic function to calculate loss as a per-1 float
+    #
+    # Arguments:
+    # * responses: (number) How many responses were received (numerator)
+    # * requests: (number) How many requests were sent (denominator)
+
+    def calc_loss(responses, requests)
+      1 - (responses.to_f/requests)
+    end
+
+  end
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: elbping
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.0.11
   prerelease: 
 platform: ruby
 authors:
@@ -11,22 +11,6 @@ bindir: bin
 cert_chain: []
 date: 2013-08-13 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: net-dns
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 0.8.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 0.8.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -43,22 +27,6 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 10.0.4
-- !ruby/object:Gem::Dependency
-  name: ipaddress
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 0.8.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: 0.8.0
 description: elbping is a tool to ping all of the nodes behind an Amazon Elastic Load
   Balancer. It only works for ELBs in HTTP mode and works by triggering an HTTP 405
   (METHOD NOT ALLOWED) error caused when the ELB receives a HTTP verb that is too
@@ -73,6 +41,7 @@ files:
 - lib/elbping/display.rb
 - lib/elbping/pinger.rb
 - lib/elbping/resolver.rb
+- lib/elbping/stats.rb
 - bin/elbping
 homepage: https://github.com/chooper/elbping
 licenses: