rubix 0.0.8 → 0.0.9

data/lib/rubix/sender.rb

@@ -2,36 +2,69 @@ require 'rubix/log'
 
 module Rubix
 
+  # A class used to send data to Zabbix.
+  #
+  # This sender is used to implement the logic for the +zabbix_pipe+
+  # utility.  It is initialized with some metadata about a host, its
+  # host groups and templates, and applications into which items
+  # should be written, and it can then accept data and forward it to a
+  # Zabbix server using the +zabbix_sender+ utility that comes with
+  # Zabbix.
+  #
+  # A sender can be given data in either TSV or JSON formats.  With
+  # the JSON format, it is possible to embed data for hosts, host
+  # groups, &c. distinct from that with which this sender was
+  # initialized.  This is a useful way to send many different kinds of
+  # data through the same process.
+  #
+  # The sender will also auto-vivify any hosts, host gruops,
+  # templates, applications, and items it needs in order to be able to
+  # write data.  This is expensive in terms of time so it can be
+  # turned off using the <tt>--fast</tt> option.
   class Sender
 
     include Logs
 
-    # A Hash of options.
+    # @return [Hash] settings
     attr_accessor :settings
 
-    # The host the Sender will send data for.
+    # @return [Rubix::Host] the host the Sender will send data for
     attr_accessor :host
 
-    # The hostgroups used to create this host.
+    # @return [Array<Rubix::HostGroup>] the hostgroups used to create this host
     attr_accessor :host_groups
 
-    # The templates used to create this host.
+    # @return [Array<Rubix::Template>] the templates used to create this host
     attr_accessor :templates
 
-    # The applications used to create items.
+    # @return [Array<Rubix::Application>] The applications used to create items
     attr_accessor :applications
     
     #
-    # Initialization
+    # == Initialization ==
     #
 
+    # Create a new sender with the given +settings+.
+    #
+    # @param [Hash, Configliere::Param] settings
+    # @param settings [String] host the name of the Zabbix host to write data for
+    # @param settings [String] host_groups comma-separated names of Zabbix host groups the host should belong to
+    # @param settings [String] templates comma-separated names of Zabbix templates the host should belong to
+    # @param settings [String] applications comma-separated names of applications created items should be scoped under
+    # @param settings [String] server URL for the Zabbix server -- *not* the URL for the Zabbix API
+    # @param settings [String] configuration_file path to a local Zabbix configuration file as used by the +zabbix_sender+ utility
+    # @param settings [true, false] verbose be verbose during execution
+    # @param settings [true, false] fast auto-vivify (slow) or not (fast)
+    # @param settings [String] pipe path to a named pipe to be read from
+    # @param settings [Fixnum] pipe_read_sleep seconds to sleep after an empty read from the a named pipe
+    # @param settings [Fixnum] create_item_sleep seconds to sleep after creating a new item
     def initialize settings
       @settings = settings
       confirm_settings
       if fast?
         info("Forwarding for #{settings['host']}...") if settings['verbose']
       else
-        initialize_hostgroups
+        initialize_host_groups
         initialize_templates
         initialize_host
         initialize_applications
@@ -39,29 +72,52 @@ module Rubix
       end
     end
 
+    # Is this sender running in 'fast' mode?  If so, it will *not*
+    # auto-vivify any hosts, groups, items, &c.
+    #
+    # @return [true, false]
     def fast?
       settings['fast']
     end
 
+    # Will this sender auto-vivify hosts, groups, items, &c.?
+    # 
+    # @return [true, false]
     def auto_vivify?
       !fast?
     end
-    
-    def initialize_hostgroups
+
+    protected
+
+    # Find or create necessary host groups.
+    #
+    # @return [Array<Rubix::HostGroup>]
+    def initialize_host_groups
       self.host_groups = settings['host_groups'].split(',').flatten.compact.map { |group_name | HostGroup.find_or_create(:name => group_name.strip) }
     end
 
+    # Find necessary templates.
+    #
+    # @return [Array<Rubix::Template>]
     def initialize_templates
       self.templates = (settings['templates'] || '').split(',').flatten.compact.map { |template_name | Template.find(:name => template_name.strip) }.compact
     end
 
+    # Find or create the host for this data.  Host groups and
+    # templates will automatically be attached.
+    #
+    # @return [Rubix::Host]
     def initialize_host
       self.host = (Host.find(:name => settings['host']) || Host.new(:name => settings['host']))
-      host.host_groups = host_groups
-      host.templates   = templates
+      host.host_groups = ((host.host_groups || []) + host_groups).flatten.compact.uniq
+      host.templates   = ((host.templates || []) + templates).flatten.compact.uniq
       host.save
+      host
     end
 
+    # Find or create the applications for this data.
+    #
+    # @return [Array<Rubix::Application>]
     def initialize_applications
       application_names = (settings['applications'] || '').split(',').flatten.compact
       self.applications = []
@@ -78,19 +134,28 @@ module Rubix
           end
         end
       end
+      self.applications
     end
 
+    # Check that all settings are correct in order to be able to
+    # successfully write data to Zabbix.
     def confirm_settings
       raise ConnectionError.new("Must specify a Zabbix server to send data to.")     unless settings['server']
       raise Error.new("Must specify the path to a local configuraiton file")         unless settings['configuration_file'] && File.file?(settings['configuration_file'])
       raise ConnectionError.new("Must specify the name of a host to send data for.") unless settings['host']
       raise ValidationError.new("Must define at least one host group.")              if auto_vivify? && (settings['host_groups'].nil? || settings['host_groups'].empty?)
     end
+
+    public
     
     #
-    # Actions
+    # == Sending Data == 
     #
 
+    # Run this sender.
+    #
+    # Will read from the correct source of data and exit the Ruby
+    # process once the source is consumed.
     def run
       case
       when settings['pipe']
@@ -104,8 +169,12 @@ module Rubix
       end
       exit(0)
     end
+
+    protected
     
-    # Process each line of the file at +path+.
+    # Process each line of a file.
+    #
+    # @param [String] path the path to the file to process
     def process_file path
       f = File.new(path)
       process_file_handle(f)
@@ -118,6 +187,10 @@ module Rubix
     end
     
     # Process each line read from the pipe.
+    #
+    # The pipe will be opened in a non-blocking read mode.  This
+    # sender will wait 'pipe_read_sleep' seconds between successive
+    # empty reads.
     def process_pipe
       # We want to open this pipe in non-blocking read mode b/c
       # otherwise this process becomes hard to kill.
@@ -133,7 +206,9 @@ module Rubix
       f.close
     end
     
-    # Process each line of a given file handle +f+.
+    # Process each line of a given file handle.
+    #
+    # @param [File] f the file to process
     def process_file_handle f
       begin
         line = f.readline
@@ -152,7 +227,12 @@ module Rubix
         end
       end
     end
+
+    public
     
+    # Process a single line of text.
+    #
+    # @param [String] line
     def process_line line
       if looks_like_json?(line)
         process_line_of_json_in_new_pipe(line)
@@ -161,6 +241,8 @@ module Rubix
       end
     end
 
+    protected
+
     # Parse and send a single +line+ of TSV input to the Zabbix server.
     # The line will be split at tabs and expects either
     #
@@ -168,6 +250,8 @@ module Rubix
     #   b) three columns: an item key, a value, and a timestamp
     #
     # Unexpected input will cause an error to be logged.
+    #
+    # @param [String] line a line of TSV data
     def process_line_of_tsv_in_this_pipe line
       parts = line.strip.split("\t")
       case parts.size
@@ -181,7 +265,7 @@ module Rubix
         error("Each line of input must be a tab separated row consisting of 2 columns (key, value) or 3 columns (timestamp, key, value)")
         return
       end
-      send(key, value, timestamp)
+      send_data(key, value, timestamp)
     end
 
     # Parse and send a single +line+ of JSON input to the Zabbix server.
@@ -214,6 +298,8 @@ module Rubix
     #       {'key': 'snap.crackle.pop', 'value': 8 }
     #     ]
     #   }
+    #
+    # @param [String] line a line of JSON data
     def process_line_of_json_in_new_pipe line
       begin
         json = JSON.parse(line)
@@ -256,9 +342,12 @@ module Rubix
       end
     end
 
-    # Does the line look like it might be JSON?
+    # Does the +line+ look like it might be JSON?
+    #
+    # @param [String] line
+    # @return [true, false]
     def looks_like_json? line
-      line =~ /^\s*\{/
+      !!(line =~ /^\s*\{/)
     end
 
     # Send the +value+ for +key+ at the given +timestamp+ to the Zabbix
@@ -266,7 +355,13 @@ module Rubix
     #
     # If the +key+ doesn't exist for this local agent's host, it will be
     # added.
-    def send key, value, timestamp
+    #
+    # FIXME passing +timestamp+ has no effect at present...
+    #
+    # @param [String] key
+    # @param [String, Fixnum, Float] value
+    # @param [Time] timestamp
+    def send_data key, value, timestamp
       ensure_item_exists(key, value) unless fast?
       command = "#{settings['sender']} --config #{settings['configuration_file']} --zabbix-server #{settings['server']} --host #{settings['host']} --key #{key} --value '#{value}'"
       process_zabbix_sender_output(key, `#{command}`)
@@ -279,6 +374,10 @@ module Rubix
       # end
     end
 
+    # Create an item for the given +key+ if necessary.
+    #
+    # @param [String] key
+    # @param [String, Fixnum, Float] value
     def ensure_item_exists key, value
       item = Item.find(:key => key, :host_id => host.id)
       unless item
@@ -301,6 +400,10 @@ module Rubix
     end
     
     # Parse the +text+ output by +zabbix_sender+.
+    #
+    # @param [String] key
+    # @param [String] text the output from +zabbix_sender+
+    # @return [Fixnum] the number of data points processed
     def process_zabbix_sender_output key, text
       return unless settings['verbose']
       lines = text.strip.split("\n")
@@ -309,6 +412,7 @@ module Rubix
       status_line =~ /Processed +(\d+) +Failed +(\d+) +Total +(\d+)/
       processed, failed, total = $1, $2, $3
       warn("Failed to write #{failed} values to key '#{key}'") if failed.to_i != 0
+      processed
     end
 
   end

data/spec/requests/application_request_spec.rb

@@ -1,49 +1,47 @@
 require 'spec_helper'
 
-describe "CRUD for hosts" do
+describe "Applications" do
 
   before do
-    @hg = Rubix::HostGroup.new(:name => 'rubix_spec_host_group_1')
-    ensure_save(@hg)
-    
-    @h1  = Rubix::Host.new(:name => 'rubix_spec_host_1', :host_groups => [@hg])
-    ensure_save(@h1)
-
-    @h2  = Rubix::Host.new(:name => 'rubix_spec_host_2', :host_groups => [@hg])
-    ensure_save(@h2)
+    integration_test
+    @host_group = ensure_save(Rubix::HostGroup.new(:name => 'rubix_spec_host_group_1'))
+    @host = ensure_save(Rubix::Host.new(:name => 'rubix_spec_host_1', :host_groups => [@host_group]))
   end
 
   after do
-    ensure_destroy(@h1, @h2, @hg)
+    truncate_all_tables
   end
-  
-  it "should be able to create, update, and destroy a host" do
-    integration_test
-    
-    Rubix::Application.find(:name => 'rubix_spec_app_1', :host_id => @h1.id).should be_nil
-    
-    app1 = Rubix::Application.new(:name => 'rubix_spec_app_1', :host_id => @h1.id)
-    app1.save.should be_true
-    id = app1.id
-    id.should_not be_nil
-    
-    ensure_destroy(app1) do
-      
-      app2 = Rubix::Application.find(:name => 'rubix_spec_app_1', :host_id => @h1.id)
-      app2.should_not be_nil
-      app2.id.should == app1.id
-      app2.host_id.should == @h1.id
-      
-      app1.name = 'rubix_spec_app_2'
-      app1.save.should be_true
-      
-      app2 = Rubix::Application.find(:id => id, :name => 'rubix_spec_app_2', :host_id => @h1.id)
-      app2.should_not be_nil
-      app2.name.should == 'rubix_spec_app_2'
-      
-      app1.destroy.should be_true
-      Rubix::Application.find(:id => id, :host_id => @h1.id).should be_nil
-      Rubix::Application.find(:id => id, :host_id => @h2.id).should be_nil
+
+  describe "when not existing" do
+
+    it "returns nil on find" do
+      Rubix::Application.find(:name => 'rubix_spec_app_1', :host_id => @host.id).should be_nil
+    end
+
+    it "can be created" do
+      app = Rubix::Application.new(:name => 'rubix_spec_app_1', :host_id => @host.id)
+      app.save.should be_true
     end
+
+  end
+
+  describe "when existing" do
+
+    before do
+      @app = ensure_save(Rubix::Application.new(:name => 'rubix_spec_app_1', :host_id => @host.id))
+    end
+
+    it "can have its name changed" do
+      @app.name = 'rubix_spec_app_2'
+      @app.save
+      Rubix::Application.find(:name => 'rubix_spec_app_1', :host_id => @host.id).should     be_nil
+      Rubix::Application.find(:name => 'rubix_spec_app_2', :host_id => @host.id).should_not be_nil
+    end
+
+    it "can be destroyed" do
+      @app.destroy
+      Rubix::Application.find(:name => 'rubix_spec_app_1', :host_id => @host.id).should be_nil
+    end
+    
   end
 end

data/spec/requests/host_group_request_spec.rb

@@ -1,31 +1,49 @@
 require 'spec_helper'
 
-describe "CRUD for host groups" do
+describe "HostGroups" do
 
-  it "should be able to create, update, and destroy a host group" do
+  before do
     integration_test
+  end
+
+  after do
+    truncate_all_tables
+  end
+
+  describe "when not existing" do
+    
+    it "returns nil on find" do
+      Rubix::HostGroup.find(:name => 'rubix_spec_host_group_1').should be_nil
+    end
+
+    it "can be created" do
+      hg = Rubix::HostGroup.new(:name => 'rubix_spec_host_group_1')
+      hg.save.should be_true
+    end
     
-    Rubix::HostGroup.find(:name => 'rubix_spec_host_group_1').should be_nil
+  end
+
+  describe "when existing" do
+
+    before do
+      @hg = ensure_save(Rubix::HostGroup.new(:name => 'rubix_spec_host_group_1'))
+    end
     
-    hg1 = Rubix::HostGroup.new(:name => 'rubix_spec_host_group_1')
-    hg1.save.should be_true
-    id = hg1.id
-    id.should_not be_nil
-
-    ensure_destroy(hg1) do
-      hg2 = Rubix::HostGroup.find(:name => 'rubix_spec_host_group_1')
-      hg2.should_not be_nil
-      hg2.name.should == 'rubix_spec_host_group_1'
-      
-      hg1.name = 'rubix_spec_host_group_2'
-      hg1.save.should be_true
-
-      hg2 = Rubix::HostGroup.find(:name => 'rubix_spec_host_group_2')
-      hg2.should_not be_nil
-      hg2.name.should == 'rubix_spec_host_group_2'
-
-      hg1.destroy
-      Rubix::HostGroup.find(:id => id).should be_nil
+    it "can be found" do
+      Rubix::HostGroup.find(:name => 'rubix_spec_host_group_1').should_not be_nil
+    end
+
+    it "can have its name changed" do
+      @hg.name = 'rubix_spec_host_group_2'
+      @hg.save
+      Rubix::HostGroup.find(:name => 'rubix_spec_host_group_1').should     be_nil
+      Rubix::HostGroup.find(:name => 'rubix_spec_host_group_2').should_not be_nil
+    end
+
+    it "can be destroyed" do
+      @hg.destroy
+      Rubix::HostGroup.find(:name => 'rubix_spec_host_group_1').should be_nil
     end
   end
+  
 end