= Rubix

{}[http://travis-ci.org/infochimps-labs/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. - host.get, template.delete, &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 zabbix_api --help for more details.

=== Logging

Rubix produces log messages at the Logger::INFO level to a +Logger+ instance by default. When the logger severity is Logger::DEBUG 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: host.items.

== 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 memory_monitor.rb 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