= 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'
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?
# means we found our host.
puts response.result
#=> [{"hostid"=>"10017"}]
when response.success?
# such host!
puts "No such host"
else
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')
host_group = Rubix::HostGroup.find_or_create(:name => "My Zabbix Hosts")
template = Rubix::Template.new(:name => "Template_Some_Service") template.save
host = Rubix::Host.new(:name => "My Host", :ip => '123.123.123.123', :templates => [template], :host_groups => [host_group]) host.save
app = Rubix::Application.new(:name => 'Some App', :host => host) app.save
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.
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