= Rubix

Rubix is a Ruby client for Zabbix[http://www.zabbix.com/] that makes
it easier to programatically control Zabbix resources so that they can
be coordinated in complex, dynamic, and distributed environments like
clouds.

Rubix provides a wrapper for the {Zabbix API
documentation}[http://www.zabbix.com/documentation/1.8/api] and an ORM
for resources like Hosts, HostGroups, Templates, Items, &c.

Rubix also provides simple command line tools and Ruby classes that
make it easier to query Zabbix and send it data.

There are a lot of other projects out there that connect Ruby to
Zabbix.  Here's a quick list:

zabbix[http://github.com/lorieri/zabbix]::
  zabbix aws templates, scripts, chef automations

zabbixapi[http://github.com/verm666/zabbixapi]::
  Ruby module for work with zabbix api
  
zabbix-rb[http://github.com/mhat/zabbix-rb]::
  send data to zabbix from ruby
  
zabbix_pusher[http://github.com/iteh/zabbix_pusher]::
  zabbix_pusher is a gem to parse zabbix templates and push the data
  to the corresponding zabbix server

zabbix-trappers[http://github.com/vzctl/zabbix-trappers]::
  Collection of ruby scripts for zabbix trappers
  
rzabbix[http://github.com/neerfri/rzabbix]::
  Zabbix API client for Ruby

zabboard[http://github.com/yammer/zabboard]::
  zabbix analytics
  
zabbix-web[http://github.com/legiar/zabbix-web]::
  Zabbix frontend

zabcon[http://trac.red-tux.net/]::
  Zabcon is a command line interface for Zabbix written in Ruby

== Connections, Requests, & Responses

Getting connected to the Zabbix API is easy

  require 'rubix'

  # Provide API URL & credentials.  These are the defaults.
  Rubix.connect('http://localhost/api_jsonrpc.php', 'admin', 'zabbix')

As per the {Zabbix API
documentation}[http://www.zabbix.com/documentation/1.8/api] each
request to the Zabbix API needs four values:

+id+::
  an integer identifying the request ID.

+auth+::
  a string confirming that the API request is authenticated.

+method+::
  the name of the API method you're calling, e.g. - <tt>host.get</tt>, <tt>template.delete</tt>, &c.

+params+::
  parameters for the invocation of the +method+.

When you send a request, Rubix only requires you to specify the
+method+ and the +params+, handling the +id+ and authentication
quietly for you:

  response = Rubix.connection.request('host.get', 'filter' => { 'host' => 'My Zabbix Host' })

  case
  when response.has_data?
    # Response is a success and "has data" -- it's not empty.  This
    # means we found our host.
    puts response.result
    #=> [{"hostid"=>"10017"}]
  when response.success?
    # Response was succssful but doesn't "have data" -- it's empty, no
    # such host!
    puts "No such host"
  else
    # Response was an error.  Uh oh!
    puts response.error_message
  end
  
=== On the command line

Rubix comes with a command line utility +zabbix_api+ which lets you
issue these sorts of requests directly on the command line.

  $ zabbix_api host.get '{"filter": {"host": "My Zabbix Host"}}'
  [{"hostid"=>"10017"}]

+zabbix_api+ lets you specify the credentials and will pretty-print
responses for you.  Try <tt>zabbix_api --help</tt> for more details.

=== Logging

Rubix produces log messages at the <tt>Logger::INFO</tt> level to a
+Logger+ instance by default.  When the logger severity is
<tt>Logger::DEBUG</tt> Rubix will log the request and response to
every API call it makes against the Zabbix API.  This can be useful
when debugging why a particular interaction isn't working as expected.

Besides programatically modifying the logger, the log level and path
can be modified at runtime with the environment variables
+RUBIX_LOG_LEVEL+ and +RUBIX_LOG_PATH+.

== ORM

If you don't want to deal with the particulars of the Zabbix API
itself, Rubix provides a set of classes that you can use instead.

The following example goes through setting up an item on a host
complete with host groups, templates, applications, and so on.

  require 'rubix'
  Rubix.connect('http://localhost/api_jsonrpc.php', 'admin', 'zabbix')

  # Ensure the host group we want exists.
  host_group = Rubix::HostGroup.find_or_create(:name => "My Zabbix Hosts")

  # Now the template -- created templates are empty by default!
  template = Rubix::Template.new(:name => "Template_Some_Service")
  template.save
  
  # Now the host.
  host = Rubix::Host.new(:name => "My Host", :ip => '123.123.123.123', :templates => [template], :host_groups => [host_group])
  host.save

  # Now for the application
  app = Rubix::Application.new(:name => 'Some App', :host => host)
  app.save

  # Now the item
  item = Rubix::Item.new(:host => host, :key => 'foo.bar.baz', :description => "Some Item", :value_type => :unsigned_int, :applications => [app])
  item.save

You can also +update+ and +destroy+ resources as well as probe
associations: <tt>host.items</tt>.

== Monitors

Rubix also comes with some classes that make it easy to write simple
monitors.  The output of these monitors should match the expected
input format of +zabbix_pipe+.  This way they can be chained together.
Here's an example of a simple monitor that calculates the currently
used memory in bytes.

  # in memory_monitor.rb
  require 'rubix'

  class MemoryMonitor < Rubix::Monitor
    def measure
      write do |data|
        mem_used = `free | tail -n+2 | head -n1`.chomp.split[2].to_i
        data << [['mem.used', mem_used]]
      end
    end
  end

  MemoryMonitor.run if $0 == __FILE__

The file <tt>memory_monitor.rb</tt> can now be run on the command line
in various ways.  Most simply it will just output a measurement.

  $ ruby memory_monitor.rb
  'mem.used'	11595908

You can also have it loop after a number of seconds

  $ ruby memory_monitor.rb --loop=30
  'mem.used'	11595760
  'mem.used'	11595800
  'mem.used'	11596016
  'mem.used'	11596008

You can pipe the results directly to Zabbix (uses {Zabbix
sender}[http://www.zabbix.com/documentation/1.8/manual/processes/zabbix_sender]
behind the scenes):

  $ ruby memory_monitor.rb --loop=30 --send