Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A Ruby client for configuring and writing to Zabbix
Ruby
Tree: ec40086e6b

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
lib
spec
.gitignore
LICENSE
README.rdoc
Rakefile
VERSION
rubix.gemspec

README.rdoc

Rubix

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

zabbix aws templates, scripts, chef automations

zabbixapi

Ruby module for work with zabbix api

zabbix-rb

send data to zabbix from ruby

zabbix_pusher

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

zabbix-trappers

Collection of ruby scripts for zabbix trappers

rzabbix

Zabbix API client for Ruby

zabboard

zabbix analytics

zabbix-web

Zabbix frontend

zabcon

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:

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

$ ruby memory_monitor.rb --loop=30 --send
Something went wrong with that request. Please try again.