apprentice 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2eb779e8019bc7c078828dfe07fc5e539350395b
-  data.tar.gz: 0cf26b9a3a937061fa84179525ac81430a88cb23
+  metadata.gz: 5677b66a1b063db82716d77a866bed546a2e873b
+  data.tar.gz: 3cc0c846e58fccd80625fe2ed1728fc402a6d1f4
 SHA512:
-  metadata.gz: 53c07b701e099588fdcb2847bf96506f69ce9f48191a817991ac5bf4fb82dd0f7462275257cba32db5090f34e9cff6247b692038a00faf45329646b5021f11c8
-  data.tar.gz: 3ca0284cc47e6cd123bfa5b4254e8e1a74539f0a856a855cfb506b789a50d1245a438322669add466cbea638a4290ec9262177aab0ea212fce9e3a6970a3d485
+  metadata.gz: dadebfde96c397883370a51b3f3f20199245f78dd7dc451eac833fb4bbc3ce40677ad0aeb4b76a41fe90127dbab57eebaffe82ad4a34e3935e73f02c06058220
+  data.tar.gz: a210337e0c220d29f93bfc3e8d66d382c37bcf2ad304e68dfe735911627c98b386a98cdad19a0227742cba03d1b1da01374a2d2040fb17219d88b556de5eaf3c

data/README.md

@@ -1,6 +1,6 @@
 # Apprentice
 
-Apprentice is tiny server application that determines the current state of a running [MariaDB Galera master-master cluster setup](https://mariadb.com/kb/en/what-is-mariadb-galera-cluster/) and responds to HTTP requests on a pre-defined port, depending on the state of the server it is checking on.
+Apprentice is tiny server application (under 300 lines of ruby code) that determines the integrity of a running [MariaDB/MySQL slave](https://mariadb.com/kb/en/replication-overview/) or [MariaDB Galera master-master cluster member](https://mariadb.com/kb/en/what-is-mariadb-galera-cluster/) and responds to HTTP requests on a pre-defined port, depending on the state of the server it is checking on.
 
 ## How does it work?
 
@@ -10,13 +10,20 @@ You can find out about the syntax by running `apprentice --help`:
     Usage: apprentice [options]
 
     Specific options:
-        -s, --server SERVER              Connect to SERVER
-        -u, --user USER                  USER to connect the server with
+        -s, --server SERVER              SERVER to connect to
+        -u, --user USER                  USER to connect to the server with
         -p, --password PASSWORD          PASSWORD to use
+        -t, --type TYPE                  TYPE of server. Must either by "galera" or "mysql".
         -i, --ip IP                      Local IP to bind to
+                                         (default: 0.0.0.0)
             --port PORT                  Local PORT to use
-            --sql_port PORT              Port of the MariaDB server to connect to
-            --[no-]accept-donor          Accept cluster state "Donor/Desynced" as valid
+                                         (default: 3307)
+            --sql_port PORT              Port of MariaDB/MySQL server to connect to
+                                         (default: 3306)
+            --[no-]accept-donor          Accept galera cluster state "Donor/Desynced" as valid
+                                         (default: false)
+            --threshold SECONDS          MariaDB/MySQL slave lag threshold
+                                         (default: 120)
 
     Common options:
         -h, --help                       Show this message
@@ -25,7 +32,7 @@ You can find out about the syntax by running `apprentice --help`:
 
 ## What it does
 
-It determines whether or not the server it is connected to is alive and ready to serve connections to clients. Furthermore, it also determines whether said server is a healthy part of the MariaDB cluster it belongs.
+It determines whether or not the server it is connected to is alive and ready to serve connections to clients. Furthermore, it also determines whether said server is a healthy enough to serve connections, i.e. doesn't suffer from slave lag or has separated from the cluster.
 
 ## What it doesn't do
 
@@ -35,7 +42,16 @@ It determines whether or not the server it is connected to is alive and ready to
     * *`503 Service Unavailable`*: The server is unavailable and not ready for connections
 
 ## What's it checking exactly?
+###MariaDB/MySQL
+Apprentice checks the following variables:
+
+* **Slave_IO_Running**: Indicates whether a slave is actually replicating from its master. If this is set to "No" or even "nil" the server is considered unfit for serving client connections.
+* **Seconds_Behind_Master**: Indicates how far (in seconds) the slave is behind its master's state. A threshold above 120 is widely considered to be unsuitable for serving valid data. The lower the value the higher the risk of Apprentice returning a negative result.
+    * *Note*: Generally, MariaDB/MySQL slaves are lagging a little (even if it is just fractions to few seconds). A threshold value below 30 - 60 (depending on your setup) would probably be too conservative. However, YMMV.
+
+For Apprentice to be able to check on the mentioned variables the user you specify on the command line needs [the 'REPLICATION CLIENT' privileges](http://dev.mysql.com/doc/refman/5.0/en/privileges-provided.html#priv_replication-client) granted within the given server. Otherwise Apprentice is going to return a negative result.
 
+###Galera
 Apprentice checks the following variables:
 
 * **wsrep_cluster_size**: A cluster size below 2 is considered an error since there must never be one single server inside a cluster setup.
@@ -44,7 +60,8 @@ Apprentice checks the following variables:
     * *Note*: The value `2` indicates the server in question is currently being used as a donor to another member of the cluster and might be exhibiting slow-downs and/or erratic behaviour due to elevated network traffic and disc IO. For further explanation please [consult the MariaDB documentation](https://mariadb.com/kb/en/what-is-mariadb-galera-cluster/).
 
 ## That's great and all, but what gives?
-By itself, Apprentice doesn't do aynthing all that useful. However, it accommodates [HAProxy's httpchk method](http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#option%20httpchk) quite nicely, making it possible to let HAProxy not only balance connection among a large pool of MariaDB cluster servers but also check on the cluster members health while doing so. With it you needn't care about a server dropping out of the cluster and clients still connecting to it since HAProxy and Apprentice are going to take care of that failing member by taking him out of the connection pool.
+By itself, Apprentice doesn't do anything all that useful. However, it accommodates [HAProxy's httpchk method](http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#option%20httpchk) quite nicely, making it possible to let HAProxy not only balance connection among a large pool of MariaDB/MySQL slave nodes or cluster members but also check on their respected "health" while doing so.
+Usually, HAProxy would only be able to establish a connection to a server without checking on its consistency. Apprentice does that job for you and helps HAProxy make the right decision on which servers to let a client gain access to.
 
 ## Goodies
 
@@ -53,13 +70,12 @@ I've included an init.d script, `ruby-apprentice.init` which you may use in orde
 
     $ mv ruby-apprentice.init /etc/init.d/ruby-apprentice
     $ chmod +x /etc/init.d/ruby-apprentice
-    $ mv ruby-apprentice.defaults /etc/defaults/
+    $ mv ruby-apprentice.defaults /etc/defaults/ruby-apprentice
 
 Now you just need to add the relevant information for starting Apprentice. The defaults file is pretty self explanatory.
 
 ## TODO
 
-* Write better (r)docs. I'm sorry for the abysmal state they're in right now
-* Be a lot more forgiving when it comes to SQL connection errors/reconnects/server going awol.
 * Finish the rspec definitions. Sorry for missing out on those as well.
+* Maybe integrate a logger
 * Write a better init script

data/apprentice.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = Apprentice::VERSION
   spec.authors       = 'Moritz Heiber'
   spec.email         = %w{moritz.heiber@gmail.com}
-  spec.description   = 'A MariaDB cluster integrity checker'
-  spec.summary       = 'Check given servers for consistency and replication status'
+  spec.description   = 'A MariaDB/MySQL slave lag and cluster integrity checker'
+  spec.summary       = 'Checks a given server for consistency and replication status'
   spec.homepage      = 'http://github.com/moritzheiber/apprentice'
   spec.license       = 'MIT'
 

data/lib/apprentice.rb

@@ -3,15 +3,34 @@ require 'apprentice/configuration'
 require 'apprentice/version'
 require 'apprentice/server'
 
+# The main Apprentice module including all other modules and classes
 module Apprentice
+
+  # This defines the sentinel, i.e. tiny server, Apprentice uses to communicate with e.g. HAProxy's httpchk method.
   class Sentinel
-    include Configuration
-    include Server
+    include Configuration #:nodoc:
+    include Server        #:nodoc:
 
+    # This depends on the Configuration module since it uses the Configuration#get_config method.
+    #
+    # ==== Return value
+    #
+    # * <tt>@options</tt> - set the global variable <tt>@options</tt> which is used inside #run the start the EventMachine server
     def initialize
       @options = get_config
     end
 
+    # Starts the EventMachine server
+    #
+    # === Special conditions
+    #
+    # We are trapping the signals <tt>INT</tt> and <tt>TERM</tt> here in order to shut down the EventMachine gracefully.
+    #
+    # ==== Attributes
+    #
+    # * <tt>@options.ip</tt> - The server binds to this specific ip
+    # * <tt>@options.port</tt> - The server uses this specific port to expose its limited HTTP interface to the world
+    # * <tt>@options</tt> - Gets passed to the server as a whole to be used with Server::EventServer#initialize
     def run
       EM.run do
         Signal.trap('INT') { EventMachine.stop }

data/lib/apprentice/checker.rb

@@ -1,9 +1,37 @@
+# Contains all the relevant methods for checking on a server's state
+#
+# Conditionally includes either MariaDB/MySQL or Galera related checking code
 module Checker
-  require 'apprentice/checks/galera'
-  include Galera
 
+  # HTTP response codes and their respective return value
+  #
+  # We're constructing our dumb HTTP response handler using these
   CODES = {200 => 'OK',503 => 'Service Unavailable'}
 
+  case @type
+    when 'galera'
+      require 'apprentice/checks/galera'
+      include Galera
+    when 'mysql'
+      require 'apprentice/checks/mysql'
+      include Mysql_Checks
+  end
+
+  # Format our HTTP/1.1 response properly without using arbitrary line breaks.
+  #
+  # ==== Attributes
+  #
+  # * +texts+ - A hash containing all text responses returned from run_checks.
+  #
+  # ==== Return values
+  #
+  # * +value+ - The comprehensive text returned with a HTTP response.
+  #
+  # ==== Examples
+  #
+  #    t = ['Something', 'Something else']
+  #    response = format_text(t)
+  #    response.inspect # => 'Something\r\nSomething else\r\n'
   def format_text(texts)
     value = ''
     if !texts.empty?
@@ -14,6 +42,26 @@ module Checker
     return value
   end
 
+  # Generates the actual output returned by the Server::EventServer class.
+  #
+  # It's valid HTTP/1.1 and should be understood by almost any browser. Certainly by HAProxy's httpchk.
+  #
+  # ==== Attributes
+  #
+  # * +code+ - The HTTP code for the returned response
+  # * +text+ - Formatted text to be returned with the response
+  #
+  # ==== Return values
+  #
+  # * String - A HTTP response string
+  #
+  # ==== Examples
+  #
+  #    code = 503
+  #    text = 'Something is wrong'
+  #
+  #    response = generate_response(code, text)
+  #    response.inspect # => 'HTTP/1.1 503 Service Unavailable\r\nContent-type: text/plain\r\nContent-length: 18\r\n\r\nSomething is wrong\r\n'
   def generate_response(code = 503, text)
     "HTTP/1.1 #{code} #{CODES[code]}\r\nContent-type: text/plain\r\nContent-length: #{text.length}\r\n\r\n#{text}"
   end

data/lib/apprentice/checks/galera.rb

@@ -1,6 +1,22 @@
+# Contains Galera specific methods for checking cluster member consistency
 module Galera
-  STATES = {1 => 'Joining',2 => 'Donor/Desynced',3 => 'Joined',4 => 'Synced'}
 
+  # Galera knows {a couple of different states}[http://www.percona.com/doc/percona-xtradb-cluster/wsrep-status-index.html#wsrep_local_state].
+  # This constant describes their respective meaning for user feedback and, possibly, logging purposes.
+  STATES = {1 => 'Joining', 2 => 'Donor/Desynced', 3 => 'Joined', 4 => 'Synced'}
+
+  # Gets the actual status from the Galera cluster member using the Mysql2 gem.
+  # Notice that we're using the EventMachine-enabled Mysql2::Client.
+  #
+  # Right now it only returns the relevant error output and continues working afterwards.
+  #
+  # Nothing is mentioned about explicitly closing a client connection in the Mysql2 docs,
+  # however, we need to be careful with the amount of connections we're using since we might
+  # find ourselves in an environment where the number of connections is constraint for a very few.
+  #
+  # ==== Return values
+  #
+  # * @status - Contains a hash of all the relevant wsrep_* variables to be examined by #run_checks
   def get_galera_status
     begin
       client = Mysql2::Client.new(
@@ -12,16 +28,34 @@ module Galera
       )
       result = client.query "SHOW STATUS LIKE 'wsrep_%';"
       if result.count > 0
+
+        # We need to do some conversion here in order to get a usable hash
         result.each do |r|
           @status.merge!(Hash[*r])
         end
       end
       client.close
     rescue Exception => message
+      # FIXME Properly handle exception
       puts message
     end
   end
 
+  # Returns the relevant status HTTP code accompanied by a useful user feedback text
+  #
+  # ==== Attributes
+  #
+  # * @status - Should contain a hash with the relevant information to determine the
+  #   the cluster member status. Also see #get_galera_status.
+  #
+  # ==== Return values
+  #
+  # * +response+ - A hash containing a HTTP <tt>:code</tt> and a <tt>:text</tt> to return to the user
+  #
+  # ==== Example
+  #
+  #    @status = {'wsrep_cluster_size' => 4 }
+  #    response = self.run_checks # => {:code => 503, :text => 'Some text'}
   def run_checks
     get_galera_status
     unless @status.empty?
@@ -42,16 +76,82 @@ module Galera
     end
   end
 
+  # Checks whether the cluster size as reported by the member is above 1.
+  # Any value below 2 is considered bad, as a cluster, by definition, should consist of at least
+  # 2 members connected to each other.
+  #
+  # A cluster size of 1 might also indicate a split-brain situation.
+  #
+  # ==== Return values
+  #
+  # * +true+ or +false+ - depending on the value of <tt>@status['wsrep_cluster_size']</tt>
+  #
+  # ==== Examples
+  #
+  #    @status = Hash.new
+  #
+  #    @status['wsrep_cluster_size'] = 3
+  #    r = check_cluster_size
+  #    r.inspect # => true
+  #
+  #    @status['wsrep_cluster_size'] = 1
+  #    r = check_cluster_size
+  #    r.inspect # => false
   def check_cluster_size
     return true if Integer(@status['wsrep_cluster_size']) > 1
     false
   end
 
+  # Checks whether the cluster replication is running and active.
+  # If this returns false the <tt>'wsrep_ready'</tt> status variable is set to <tt>'OFF'</tt> and thus the server is not an active
+  # member of a running cluster.
+  #
+  # ==== Return values
+  #
+  # * +true+ or +false+ - depending on the value of <tt>@status['wsrep_ready']</tt>
+  #
+  # ==== Examples
+  #
+  #    @status = Hash.new
+  #
+  #    @status['wsrep_ready'] = 'ON'
+  #    r = check_ready_state
+  #    r.inspect # => true
+  #
+  #    @status['wsrep_ready'] = 'OFF'
+  #    r = check_ready_state
+  #    r.inspect # => false
   def check_ready_state
     return true if @status['wsrep_ready'] == 'ON'
     false
   end
 
+  # Checks how the cluster member sees itself in terms of status
+  #
+  # Valid states, read from the <tt>'wsrep_local_state'</tt> variable and depending on the configuration, are <tt>4</tt>, meaning <tt>Synced</tt>, or <tt>2</tt>,
+  # meaning <tt>Donor/Desynced</tt>, if the option <tt>--accept-donor</tt> was passed at runtime.
+  #
+  # ==== Return values
+  #
+  # * +true+ or +false+ - depending on the value of <tt>@status['wsrep_local_state']</tt>
+  #
+  # ==== Examples
+  #
+  #    @status = Hash.new
+  #    @donor_allowed = false
+  #
+  #    @status['wsrep_local_state'] = 4
+  #    r = check_local_state
+  #    r.inspect # => true
+  #
+  #    @status['wsrep_local_state'] = 2
+  #    r = check_local_state
+  #    r.inspect # => false
+  #
+  #    @donor_allowed = true
+  #    @status['wsrep_local_state'] = 2
+  #    r = check_local_state
+  #    r.inspect # => true
   def check_local_state
     s = Integer(@status['wsrep_local_state'])
     return true if s == 4 || (s == 2 && @donor_allowed)

data/lib/apprentice/checks/mysql.rb

@@ -0,0 +1,127 @@
+# Contains MariaDB/MySQL specific methods for checking on slave health
+module Mysql_Checks
+
+  # Gets the actual status from the MariaDB/MySQL slave using the Mysql2 gem.
+  # Notice that we're using the EventMachine-enabled Mysql2::Client.
+  #
+  # Right now it only returns the relevant error output and continues working afterwards.
+  #
+  # Nothing is mentioned about explicitly closing a client connection in the Mysql2 docs,
+  # however, we need to be careful with the amount of connections we're using since we might
+  # find ourselves in an environment where the number of connections is constraint for a very few.
+  #
+  # ==== Return values
+  #
+  # * @status - Contains a hash of all the relevant replication related variables to be examined by #run_checks
+  def get_mysql_status
+    begin
+      client = Mysql2::Client.new(
+          host: @server,
+          port: @sql_port,
+          username: @user,
+          password: @password
+      )
+      result = client.query 'SHOW SLAVE STATUS;'
+      if result.count > 0
+        result.each do |key, state|
+          @status[key] = state
+        end
+      end
+      client.close
+    rescue Exception => message
+      puts message
+    end
+  end
+
+  # Get the value of <tt>'Slave_IO_Running'</tt>, which, obviously, should be <tt>Yes</tt> since otherwise
+  # it would mean the slave is not replicated properly and/or has stopped because of an error.
+  #
+  # ==== Attributes
+  #
+  # * <tt>@status</tt> - Uses the <tt>'Slave_IO_Running'</tt> key inside the hash.
+  #
+  # ==== Return values
+  #
+  # +true+ or +false+ - depending on whether or not the slave's replication thread is running.
+  #
+  # ==== Examples
+  #
+  #    @status = Hash.new
+  #    @status['Slave_IO_Running'] = 'Yes'
+  #
+  #    r = check_slave_io
+  #    r.inspect # => true
+  #
+  #    @status['Slave_IO_Running'] = 'No'
+  #
+  #    r = check_slave_io
+  #    r.inspect # => false
+  def check_slave_io
+    return true if @status['Slave_IO_Running'] == 'Yes'
+    false
+  end
+
+  # Get the value of <tt>'Seconds_Behind_Master'</tt>, which indicates the amount of time in seconds
+  # the slave is behind the master's instruction set received via the replication thread. This should
+  # always be as close to zero as possible (or even zero). If this value is beyond <tt>@threshold</tt>
+  # constantly you will need to think about changing your setup to accommodate the traffic coming in
+  # from the master.
+  #
+  # ==== Attributes
+  #
+  # * <tt>@status</tt> - Uses the <tt>'Seconds_Behind_Master'</tt> key inside the hash
+  # * <tt>@threshold</tt> - The globally defined threshold after which the slave is considered to be too far behind to still be an active member. The default is 120 seconds.
+  #
+  # ==== Return values
+  #
+  # +true+ or +false+ - depending on whether or not the slave's replication thread is behind <tt>@threshold</tt>
+  #
+  # ==== Examples
+  #
+  #    @status = Hash.new
+  #    @status['Slave_IO_Running'] = 'Yes'
+  #
+  #    r = check_slave_io
+  #    r.inspect # => true
+  #
+  #    @status['Slave_IO_Running'] = 'No'
+  #
+  #    r = check_slave_io
+  #    r.inspect # => false
+  def check_seconds_behind
+    return true if Integer(@status['Seconds_Behind_Master']) < @threshold
+  end
+
+  # Returns the relevant status HTTP code accompanied by a useful user feedback text
+  #
+  # ==== Attributes
+  #
+  # * @status - Should contain a hash with the relevant information to determine the
+  #   the cluster member status. Also see #get_mysql_status.
+  #
+  # ==== Return values
+  #
+  # * +response+ - A hash containing a HTTP <tt>:code</tt> and a <tt>:text</tt> to return to the user
+  #
+  # ==== Example
+  #
+  #    @status = {'Seconds_Behind_Master' => 140 }
+  #    response = self.run_checks
+  #    response.inspect # => {:code => 503, :text => 'Some text'}
+  def run_checks
+    get_mysql_status
+    unless @status.empty?
+      response = {code: 200, text: []}
+      if !check_slave_io
+        response[:text] << 'Slave IO is not running.'
+      end
+      if !check_seconds_behind
+        response[:text] << "Slave is #{@status['Seconds_Behind_Master']} seconds behind. Threshold is #{@threshold}"
+      end
+      response[:code] = 503 unless response[:text].empty?
+      return response
+    else
+      return {code: 503, text: ['Unable to determine slave status']}
+    end
+  end
+end

data/lib/apprentice/configuration.rb

@@ -1,13 +1,41 @@
 require 'optparse'
 require 'ostruct'
 
+# This module contains all the command line configuration methods
 module Configuration
+
+  # Reads ARGV with OptionParser and return an OpenStruct object with the parsed values
+  #
+  # ==== Default values
+  #
+  # * +ip+ - By default Apprentice binds to 0.0.0.0.
+  # * +port+ - The port Apprentice binds to. It defaults to 3307.
+  # * +sql_port+ - The port the MariaDB/MySQL server listens on Apprentice connects to. Defaults to 3306.
+  # * +threshold+ - The acceptable slave lag in seconds. Defaults to 120 seconds. It only applies when the type is set to 'mysql'.
+  # * +accept_donor+ - If passed, cluster members in the state '2' aka "Donor/Desynced" are accepted as valid client providers. Defaults to false, which is recommended.
+  #
+  # ==== Attributes
+  #
+  # * +ARGV+
+  #
+  # ==== Return values
+  #
+  # * +options+ - OpenStruct object containing all options passed with ARGV
+  #
+  # ==== Example
+  #
+  #    ARGV = "--user user --password password --server server"
+  #    opt = get_config
+  #    opt.user     # => 'user'
+  #    opt.password # => 'password'
+  #    opt.server   # => 'server'
   def get_config
     options = OpenStruct.new
     options.ip = '0.0.0.0'
     options.port = 3307
     options.sql_port = 3306
     options.accept_donor = false
+    options.threshold = 120
 
     opt_parser = OptionParser.new do |opts|
       opts.banner = "Usage: apprentice [options]\n"
@@ -15,20 +43,29 @@ module Configuration
       opts.separator 'Specific options:'
 
       opts.on('-s SERVER', '--server SERVER',
-        'Connect to SERVER') { |s| options.server = s }
+        'SERVER to connect to') { |s| options.server = s }
       opts.on('-u USER', '--user USER',
-        'USER to connect the server with') { |u| options.user = u }
+        'USER to connect to the server with') { |u| options.user = u }
       opts.on('-p PASSWORD', '--password PASSWORD',
         'PASSWORD to use') { |p| options.password = p }
+      opts.on('-t TYPE', '--type TYPE',
+        'TYPE of server. Must either by "galera" or "mysql".') { |t| options.type = t }
 
       opts.on('-i', '--ip IP',
-        'Local IP to bind to') { |i| options.ip = i }
+        'Local IP to bind to',
+        "(default: #{options.ip})") { |i| options.ip = i }
       opts.on('--port PORT',
-        'Local PORT to use') { |p| options.port = p }
+        'Local PORT to use',
+        "(default: #{options.port})") { |p| options.port = p }
       opts.on('--sql_port PORT',
-        'Port of the MariaDB server to connect to') { |p| options.sql_port = p }
+        'Port of MariaDB/MySQL server to connect to',
+        "(default: #{options.sql_port})") { |p| options.sql_port = p }
       opts.on('--[no-]accept-donor',
-        'Accept cluster state "Donor/Desynced" as valid') { |ad| options.accept_donor = ad }
+        'Accept galera cluster state "Donor/Desynced" as valid',
+        "(default: #{options.accept_donor})") { |ad| options.accept_donor = ad }
+      opts.on('--threshold SECONDS',
+        'MariaDB/MySQL slave lag threshold',
+        "(default: #{options.threshold})") { |tr| options.threshold = tr }
 
       opts.separator ''
       opts.separator 'Common options:'
@@ -44,10 +81,19 @@ module Configuration
     end
 
     begin
-      ARGV << 's-h' if ARGV.size < 3
       opt_parser.parse!(ARGV)
-      unless options.server && options.user && options.password
-        $stderr.puts 'Error: you have to specify a user, a password and the server to connect to'
+
+      # We need four variables:
+      # * user: a valid mysql user
+      # * password: the corresponding password
+      # * server: the server to connect to
+      # * type: either mysql or galera, depending on the setup
+      unless options.server &&
+          options.user &&
+          options.password &&
+          check_type(options.type)
+        $stderr.puts 'Error: you have to specify a user, a password, a server to connect to'
+        $stderr.puts 'and a valid type. It can either by "galera" or "mysql".'
         $stderr.puts 'Try -h/--help for more options'
         exit
       end
@@ -57,4 +103,29 @@ module Configuration
       exit
     end
   end
+
+  # Check the user input for a valid type
+  #
+  # ==== Attributes
+  #
+  # * +type+ - the type extracted from ARGV
+  #
+  # ==== Return values
+  #
+  # Either true or false, depending on whether the input provided
+  # matches either 'mysql' or 'galera'
+  #
+  # ==== Example
+  #
+  #    r = check_type('mysql')
+  #    r.inspect # => 'true'
+  #
+  #    r = check_type('something else')
+  #    r.inspect # => 'false'
+  def check_type(type)
+    %w{galera mysql}.each do |t|
+      return true if t == type
+    end
+    false
+  end
 end

data/lib/apprentice/server.rb

@@ -1,12 +1,14 @@
+# Main server module consisting of all server related methods and classes
 module Server
+
+  # The actual EM::Connection instance referenced by the EventServer class.
+  # Notice that we use Mysql2::Client::EM instead of the regular Mysql2::Client class.
   class EventServer < EM::Connection
     require 'apprentice/checker'
     require 'mysql2/em'
     include Checker
 
-    attr_accessor :client
-
-    def initialize(options)
+    def initialize(options) #:nodoc:
       @ip = options.ip
       @port = options.port
       @sql_port = options.sql_port
@@ -14,9 +16,20 @@ module Server
       @user = options.user
       @password = options.password
       @donor_allowed = options.donor_allowed
+      @type = options.type
+      @threshold = options.threshold
       @status = {}
     end
 
+    # Take the raw data received on @port and run initiate the checks against the server located at @server
+    #
+    # ==== Special conditions
+    #
+    # We are sending something to our client with #send_data inside the function, depending on what #run_checks returned to us during the function call.
+    #
+    # ==== Attributes
+    #
+    # * +data+ - We receive the actual HTTP request but since we're not a full blown HTTP server we don't actually use it to any extent
     def receive_data(data)
       response = run_checks
       response_text = format_text(response[:text])

data/lib/apprentice/version.rb

@@ -1,3 +1,4 @@
+# Main Apprentice module containing the version constant and the rest of the application
 module Apprentice
-  VERSION = '0.0.5'
+  VERSION = '0.0.6' #:nodoc:
 end

data/ruby-apprentice.default

@@ -1,9 +1,17 @@
 # Set to true to start the service
 START=false
 
-# MariaDB host
+# MariaDB/MySQL host
 DBHOST=''
 # Username which shall be used to check the status
 DBUSER=''
 # Password
 DBPASSWORD=''
+# Type of server
+# This should either by 'mysql' for MariaDB/MySQL slave lag detection
+# or 'galera' for cluster member consistency checking
+TYPE=''
+# You can specify any other arguments you want to
+# Example: '--threshold 60' for an accepted slave lag of 60 seconds
+# For more options see 'apprentice --help'
+EXTRA_ARGS=''

data/ruby-apprentice.init

@@ -5,7 +5,7 @@
 # Required-Stop:
 # Default-Start:     2 3 4 5
 # Default-Stop:      0 1 6
-# Short-Description: a MariaDB cluster integrity checker
+# Short-Description: a MariaDB/MySQL slave lag and cluster integrity checker
 ### END INIT INFO
 
 NAME="`basename ${0/.sh/}`"
@@ -30,7 +30,7 @@ do_start()
     if [ ! "${START}" = "true" ]; then
       log_failure_msg "this service is disabled. Enable it in /etc/default/$NAME"
       return 2
-    elif [ ! "${DBHOST}" ] || [ ! "${DBPASSWORD}" ] || [ ! ${DBUSER} ] ; then
+    elif [ ! "${DBHOST}" ] || [ ! "${DBPASSWORD}" ] || [ ! ${DBUSER} ] || [ ! ${TYPE} ] ; then
       log_failure_msg "Missing variables inside defaults file."
       return 2
     fi
@@ -41,13 +41,13 @@ do_start()
     chown $USER:$GROUP "$pidfile_dirname"
     chmod 0750 "$pidfile_dirname"
 
-    DAEMON_ARGS="--password ${DBPASSWORD} --user ${DBUSER} --server ${DBHOST} ${EXTRA_ARGS}"
+    DAEMON_ARGS="--password ${DBPASSWORD} --user ${DBUSER} --server ${DBHOST} --type ${TYPE} ${EXTRA_ARGS}"
 
     start-stop-daemon --start --background --make-pidfile --quiet \
-	    --user ${USER} --group ${GROUP} \
+        --user ${USER} --group ${GROUP} \
             --pidfile ${PIDFILE} --exec ${DAEMON} --test > /dev/null || return 1
     start-stop-daemon --start --background --make-pidfile --quiet \
-	    --user ${USER} --group ${GROUP} \
+        --user ${USER} --group ${GROUP} \
             --pidfile ${PIDFILE} --exec ${DAEMON} -- ${DAEMON_ARGS} || return 2
     log_end_msg $?
 }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apprentice
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Moritz Heiber
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-09 00:00:00.000000000 Z
+date: 2013-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -38,7 +38,7 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: A MariaDB cluster integrity checker
+description: A MariaDB/MySQL slave lag and cluster integrity checker
 email:
 - moritz.heiber@gmail.com
 executables:
@@ -57,6 +57,7 @@ files:
 - lib/apprentice.rb
 - lib/apprentice/checker.rb
 - lib/apprentice/checks/galera.rb
+- lib/apprentice/checks/mysql.rb
 - lib/apprentice/configuration.rb
 - lib/apprentice/server.rb
 - lib/apprentice/version.rb
@@ -87,7 +88,7 @@ rubyforge_project:
 rubygems_version: 2.0.7
 signing_key: 
 specification_version: 4
-summary: Check given servers for consistency and replication status
+summary: Checks a given server for consistency and replication status
 test_files:
 - spec/lib/apprentice_spec.rb
 - spec/spec_helper.rb