rubix 0.0.8 → 0.0.9

data/README.rdoc

@@ -175,14 +175,14 @@ Zabbix.  (Credentials and addresses for the Zabbix server and the
 Zabbix API can all be customized; see the <tt>--help</tt> option.)
 
   # Send one data point -- this is tab separated!
-  $ echo "foo.bar.baz	123" | zabbix_pipe --host='My Zabbix Host'
+  $ echo "foo.bar.baz	123" | zabbix_pipe --host='My Zabbix Host' --host_groups='My Zabbix Servers,Some Other Group'
   # Send a bunch of data points in a file
-  $ cat my_data.tsv | zabbix_pipe --host='My Zabbix Host'
+  $ cat my_data.tsv | zabbix_pipe --host='My Zabbix Host' --host_groups='My Zabbix Servers,Some Other Group'
 
 You can also pass the file directly:
 
   # Send a bunch of data points in a file
-  $ zabbix_pipe --host='My Zabbix Host' my_data.tsv
+  $ zabbix_pipe --host='My Zabbix Host' --host_groups='My Zabbix Servers,Some Other Group' my_data.tsv
 
 You can also listen from a named pipe.  This is useful on a
 "production" system in which many processes may want to simply and
@@ -190,7 +190,7 @@ easily write somewhere without worrying about what happens.
 
   # In the first terminal
   $ mkfifo /dev/zabbix
-  $ zabbix_pipe --pipe=/dev/zabbix --host='My Zabbix Host'
+  $ zabbix_pipe --pipe=/dev/zabbix --host='My Zabbix Host' --host_groups='My Zabbix Servers,Some Other Group'
 
   # In another terminal
   $ echo "foo.bar.baz	123" > /dev/zabbix
@@ -204,9 +204,9 @@ This simple block of JSON doesn't really add any power to
 +zabbix_pipe+.  What becomes more interesting is that we can wedge in
 data for *diffferent* hosts, items, &c. when using JSON input:
 
-  $ echo '{"host": "My first host", "data": [{"key": "foo.bar.baz", "value": 123}, {"key": "foo.bar.baz", "value": 101}]}' > /dev/zabbix
-  $ echo '{"host": "My second host", "data": [{"key": "foo.bar.baz", "value": 123}, {"key": "foo.bar.baz", "value": 101}]}' > /dev/zabbix
-  $ echo '{"host": "My third host", "data": [{"key": "foo.bar.baz", "value": 123}, {"key": "foo.bar.baz", "value": 101}]}' > /dev/zabbix
+  $ echo '{"host": "My first host", "host_groups": "My Zabbix Servers,Some Other Group", "data": [{"key": "foo.bar.baz", "value": 123}, {"key": "foo.bar.baz", "value": 101}]}' > /dev/zabbix
+  $ echo '{"host": "My second host", "host_groups": "My Zabbix Servers,Some Other Group", "data": [{"key": "foo.bar.baz", "value": 123}, {"key": "foo.bar.baz", "value": 101}]}' > /dev/zabbix
+  $ echo '{"host": "My third host", "host_groups": "My Zabbix Servers,Some Other Group", "data": [{"key": "foo.bar.baz", "value": 123}, {"key": "foo.bar.baz", "value": 101}]}' > /dev/zabbix
 
 Rubix will switch hosts on the fly.
 
@@ -331,9 +331,9 @@ Chef[http://www.opscode.com/chef/] and so Rubix comes with a
     def measure
       begin
         if Net::HTTP.get_response(uri).code.to_i == 200
-	  availability = 1
-	else
-	  availability = 0
+          availability = 1
+        else
+          availability = 0
 	end
       rescue => e
         availability = 0

data/VERSION

@@ -1 +1 @@
-0.0.8
+0.0.9

data/lib/rubix.rb

@@ -10,15 +10,43 @@ module Rubix
   autoload :Connection,     'rubix/connection'
   autoload :Response,       'rubix/response'
   autoload :Sender,         'rubix/sender'
-  
+
+  # Set up a <tt>Connection</tt> to a Zabbix API server.
+  #
+  # Only needs to be called once.
+  #
+  #   # These are the defaults
+  #   Rubix.connect 'localhost', 'admin', 'zabbix'
+  #
+  #   # A server running on a custom port with different
+  #   # credentials...
+  #   Rubix.connect 'my.server.com:8080', 'foobar', 'bazbooz'
+  #
+  # @param [URI,String] server the address of the Zabbix API server to connect to
+  # @param [String] username the username of an existing Zabbix API <tt>User</tt> account with API access
+  # @param [String] password the password for this account
+  # @return [Rubix::Connection]
   def self.connect server, username=nil, password=nil
     self.connection = Connection.new(server, username, password)
   end
 
+  # Explicitly set the connection using a <tt>Rubix::Connection</tt>
+  # object.
+  #
+  #   Rubix.connection = Rubix::Connection.new('http://localhost/api_jsonrpc.php', 'admin', 'zabbix')
+  #
+  # @param [Rubix::Connection] connection
+  # @return [Rubix::Connection]
   def self.connection= connection
     @connection = connection
   end
 
+  # Return the current connection to a Zabbix API.  Useful for
+  # directly sending queries.
+  #
+  #   Rubix.connection.request 'host.get', :filter => { "name" => "foobar" }
+  #
+  # @return [Rubix::Connection]
   def self.connection
     @connection ||= Connection.new('http://localhost/api_jsonrpc.php', 'admin', 'zabbix')
     return @connection if @connection.authorized?
@@ -26,10 +54,21 @@ module Rubix
     @connection
   end
 
+  # Base class for Rubix errors.
   Error               = Class.new(RuntimeError)
+
+  # Errors with connecting to a Zabbix API.
   ConnectionError     = Class.new(Error)
+
+  # Error authenticating with a Zabbix API.
   AuthenticationError = Class.new(Error)
+
+  # Error in a request to a Zabbix API.
   RequestError        = Class.new(Error)
+
+  # Error detected locally in an API resource that will prevent it
+  # from being saved by the Zabbix API (i.e. - no host group for a
+  # host).
   ValidationError     = Class.new(Error)
   
 end

data/lib/rubix/associations/belongs_to_host.rb

@@ -1,13 +1,14 @@
 module Rubix
   module Associations
+
     module BelongsToHost
-      
+
       def host= h
         return unless h
         @host    = h
         @host_id = h.id
       end
-      
+
       def host
         return @host if @host
         return unless @host_id
@@ -18,7 +19,7 @@ module Rubix
         return unless hid
         @host_id = hid
       end
-      
+
       def host_id
         return @host_id if @host_id
         return unless @host

data/lib/rubix/connection.rb

@@ -6,12 +6,44 @@ require 'rubix/log'
 
 module Rubix
 
+  # Wraps and abstracts the process of connecting to a Zabbix API.
   class Connection
 
     include Logs
 
-    attr_reader :uri, :server, :auth, :request_id, :username, :password, :last_response
+    # @return [URI] The URI for the Zabbix API.
+    attr_reader :uri
 
+    # @return [Net::HTTP] the HTTP server backing the Zabbix API.
+    attr_reader :server
+
+    # @return [String] the authentication token provided by the Zabbix
+    # API for this session.
+    attr_reader :auth
+
+    # @return [Fixnum] the ID of the next request that will be sent.
+    attr_reader :request_id
+
+    # @return [String] the username of the Zabbix account used to authenticate
+    attr_reader :username
+
+    # @return [String] the password of the Zabbix account used to authenticate
+    attr_reader :password
+
+    # @return [Rubix::Response] the last response from the Zabbix API -- useful for logging purposes
+    attr_reader :last_response
+    
+    # Set up a connection to a Zabbix API.
+    #
+    # The +uri_or_string+ can be either a string or a <tt>URI</tt>
+    # object.
+    #
+    # The +username+ and +password+ provided must correspond to an
+    # existing Zabbix account with API access enabled.
+    #
+    # @param [URI,String] uri_or_string the address of the Zabbix API server to connect to
+    # @param [String] username the username of an existing Zabbix API <tt>User</tt> account with API access
+    # @param [String] password the password for this account
     def initialize uri_or_string, username=nil, password=nil
       self.uri    = uri_or_string
       @username   = username || uri.user
@@ -19,6 +51,51 @@ module Rubix
       @request_id = 0
     end
 
+    # Send a request to the Zabbix API.  Will return a Rubix::Response
+    # object.
+    #
+    # Documentation on what methods and parameters are available can
+    # be found in the {Zabbix API
+    # documentation}[http://www.zabbix.com/documentation/1.8/api]
+    #
+    #   Rubix.connection.request 'host.get', 'filter' => { 'host' => 'foobar' }
+    #
+    # @param [String] method the name of the Zabbix API method
+    # @param [Hash,Array] params parameters for the method call
+    # @retrn [Rubix::Response]
+    def request method, params
+      authorize! unless authorized?
+      till_response do
+        raw_params = {
+          :jsonrpc => "2.0",
+          :id      => request_id,
+          :method  => method,
+          :params  => params,
+          :auth    => auth
+        }
+        send_raw_request(raw_params)
+      end
+    end
+    
+    # Has this connection already been authorized and provided with a
+    # authorization token from the Zabbix API?
+    def authorized?
+      !auth.nil?
+    end
+
+    # Force the connection to execute an authorization request and
+    # renew (or set) the authorization token.
+    def authorize!
+      response = till_response { send_raw_request(authorization_params) }
+      raise AuthenticationError.new("Could not authenticate with Zabbix API at #{uri}: #{response.error_message}") if response.error?
+      raise AuthenticationError.new("Malformed response from Zabbix API: #{response.body}") unless response.string?
+      @auth = response.result
+    end
+
+    # Set the URI for this connection's Zabbix API server.
+    #
+    # @param [String, URI] uri_or_string the address of the Zabbix API.
+    # @return [Net::HTTP]
     def uri= uri_or_string
       if uri_or_string.respond_to?(:host)
         @uri = uri_or_string
@@ -29,10 +106,12 @@ module Rubix
       @server = Net::HTTP.new(uri.host, uri.port)
     end
 
-    def authorized?
-      !auth.nil?
-    end
+    protected
 
+    # The parameters used for constructing an authorization request
+    # with the Zabbix API.
+    #
+    # @return [Hash]
     def authorization_params
       {
         :jsonrpc => "2.0",
@@ -45,13 +124,17 @@ module Rubix
       }
     end
 
-    def authorize!
-      response = till_response { send_raw_request(authorization_params) }
-      raise AuthenticationError.new("Could not authenticate with Zabbix API at #{uri}: #{response.error_message}") if response.error?
-      raise AuthenticationError.new("Malformed response from Zabbix API: #{response.body}") unless response.string?
-      @auth        = response.result
-    end
-
+    # Attempt to execute a query until a non-5xx response is returned.
+    #
+    # 5xx responses can occur because the backend PHP server providing
+    # the Zabbix API can sometimes be unavailable if the serer is
+    # restarting or something like that.  We keep trying until that
+    # doesn't happen.
+    #
+    # You shouldn't have to use this method directly -- the
+    # <tt>Rubix::Connection#authorize!</tt> and
+    # <tt>Rubix::Connection#request</tt> methods already use this
+    # functionality.
     def till_response attempt=1, max_attempts=5, &block
       response = block.call
       Rubix.logger.log(Logger::DEBUG, "RECV: #{response.body}") if Rubix.logger
@@ -65,21 +148,25 @@ module Rubix
         @last_response = Response.new(response)
       end
     end
-    
-    def request method, params
-      authorize! unless authorized?
-      till_response do
-        raw_params = {
-          :jsonrpc => "2.0",
-          :id      => request_id,
-          :method  => method,
-          :params  => params,
-          :auth    => auth
-        }
-        send_raw_request(raw_params)
+
+    # Send the POST request to the Zabbix API.
+    #
+    # @param [Hash, #to_json] raw_params the complete parameters of the request.
+    # @return [Net::HTTP::Response]
+    def send_raw_request raw_params
+      @request_id += 1
+      begin
+        raw_response = server.request(raw_post_request(raw_params))
+      rescue NoMethodError, SocketError => e
+        raise RequestError.new("Could not connect to Zabbix server at #{host_with_port}")
       end
+      raw_response
     end
-
+    
+    # Generate the raw POST request to send to the Zabbix API
+    #
+    # @param [Hash, #to_json] raw_params the complete parameters of the request.
+    # @return [Net::HTTP::Post]
     def raw_post_request raw_params
       json_body = raw_params.to_json
       Rubix.logger.log(Logger::DEBUG, "SEND: #{json_body}") if Rubix.logger
@@ -89,6 +176,9 @@ module Rubix
       end
     end
 
+    # Used for generating helpful error messages.
+    #
+    # @return [String]
     def host_with_port
       if uri.port.nil? || uri.port.to_i == 80
         uri.host
@@ -97,15 +187,5 @@ module Rubix
       end
     end
 
-    def send_raw_request raw_params
-      @request_id += 1
-      begin
-        raw_response = server.request(raw_post_request(raw_params))
-      rescue NoMethodError, SocketError => e
-        raise RequestError.new("Could not connect to Zabbix server at #{host_with_port}")
-      end
-      raw_response
-    end
-
   end
 end

data/lib/rubix/log.rb

@@ -2,21 +2,40 @@ require 'logger'
 
 module Rubix
 
+  # Set the Rubix logger.  Set to +nil+ to disable all logging.
+  #
+  # @param [Logger] l the logger to use
   def self.logger= l
     @logger = l
   end
 
+  # The current Rubix logger.
+  #
+  # @return [Logger, nil]
   def self.logger
     return @logger unless @logger.nil?
     @logger = default_logger
   end
 
+  # The default logger.
+  #
+  # @return [Logger]
   def self.default_logger
     @logger       = Logger.new(default_log_path)
     @logger.level = default_log_severity
     @logger
   end
 
+  # The default logger's severity.
+  #
+  # Will attempt to read from
+  #
+  # - <tt>Settings[:log_level]</tt> if <tt>Settings</tt> is defined (see Configliere[http://github.com/infochimps/configliere])
+  # - the <tt>RUBIX_LOG_LEVEL</tt> environment variable if defined
+  #
+  # The default is 'info'.
+  #
+  # @return [Fixnum]
   def self.default_log_severity
     case
     when defined?(Settings) && Settings[:log_level]
@@ -34,6 +53,14 @@ module Rubix
     end
   end
 
+  # The default logger's path.
+  #
+  # Will attempt to read from
+  #
+  # - <tt>Settings[:log]</tt> if <tt>Settings</tt> is defined (see Configliere[http://github.com/infochimps/configliere])
+  # - the <tt>RUBIX_LOG_PATH</tt> environment variable if defined
+  #
+  # Defaults to writing <tt>stdout</tt>.
   def self.default_log_path
     case
     when defined?(Settings) && Settings[:log]
@@ -46,29 +73,46 @@ module Rubix
       $stdout
     end
   end
-      
+
+  # This module can be included by any class to enable logging to the
+  # <tt>Rubix.logger</tt>.
   module Logs
 
+    # Write a log message with severity +debug+.
+    #
+    # @param [Array<String>] args
     def debug *args
       return unless Rubix.logger
       Rubix.logger.log(Logger::DEBUG, args.join(' '))
     end
 
+    # Write a log message with severity +info+.
+    #
+    # @param [Array<String>] args
     def info *args
       return unless Rubix.logger
       Rubix.logger.log(Logger::INFO, args.join(' '))
     end
 
+    # Write a log message with severity +warn+.
+    #
+    # @param [Array<String>] args
     def warn *args
       return unless Rubix.logger
       Rubix.logger.log(Logger::WARN, args.join(' '))
     end
 
+    # Write a log message with severity +error+.
+    #
+    # @param [Array<String>] args
     def error *args
       return unless Rubix.logger
       Rubix.logger.log(Logger::ERROR, args.join(' '))
     end
 
+    # Write a log message with severity +fatal+.
+    #
+    # @param [Array<String>] args
     def fatal *args
       return unless Rubix.logger
       Rubix.logger.log(Logger::FATAL, args.join(' '))