Build Status

Rubix is a Ruby client for Zabbix 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 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 aws templates, scripts, chef automations


Ruby module for work with zabbix api


send data to zabbix from ruby


zabbix_pusher is a gem to parse zabbix templates and push the data to the corresponding zabbix server


Collection of ruby scripts for zabbix trappers


Zabbix API client for Ruby


zabbix analytics


Zabbix frontend


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 each request to the Zabbix API needs four values:


an integer identifying the request ID.


a string confirming that the API request is authenticated.


the name of the API method you're calling, e.g. - host.get, template.delete, &c.


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' })

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"
  # Response was an error.  Uh oh!
  puts response.error_message

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"}}'

zabbix_api lets you specify the credentials and will pretty-print responses for you. Try zabbix_api --help for more details.


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.


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 = => "Template_Some_Service")

# Now the host.
host = => "My Host", :ip => '', :templates => [template], :host_groups => [host_group])

# Now for the application
app = => 'Some App', :host => host)

# Now the item
item = => host, :key => '', :description => "Some Item", :value_type => :unsigned_int, :applications => [app])

You can also update and destroy resources as well as probe associations: host.items.


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 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 behind the scenes):

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