# zabbix_sender_api

This gem describes an api that takes some of the drudgery out of the task of putting together bulk data for the zabbix_sender utility.

zabbix_sender is a command line utility for sending monitoring data to Zabbix server or proxy. On the Zabbix server an item of type Zabbix trapper should be created with corresponding key.

 * [Zabbix sender manpage](https://www.zabbix.com/documentation/4.0/manpages/zabbix_sender)
 * [Zabbix sender CLI help](zabbix-sender-help.md)


zabbix_sender_api's function is to generate data to send to a zabbix_sender instance via stdin where zabbix_sender was invoked with these options:

```
  -i --input-file input-file   Load values from input file. Specify - for
                             standard input. Each line of file contains
                             whitespace delimited: <host> <key> <value>.
                             Specify - in <host> to use hostname from
                             configuration file or --host argument
                             
  -T --with-timestamps       Each line of file contains whitespace delimited:
                             <host> <key> <timestamp> <value>. This can be used
                             with --input-file option. Timestamp should be
                             specified in Unix timestamp format
```

It is analogous to:

 \<program that generates sender input\> | zabbix-sender -z \<zabbix-server-or-proxy-ip\> -T -i -
 
(You can use this api to just generate output that you then pipe to zabbix_sender yourself if you prefer)
 

## Installation

    $ gem install zabbix_sender_api

## Usage

### Synopsis
```ruby
#!/usr/bin/env ruby
require 'zabbix_sender_api'

sender = Zabbix::Sender.new

rawdata = { :myFirstKey => 0, :mySecondKey => 100 }

data = Zabbix::Batch.new

rawdata.each_pair {|key,value|
  data.addItemData(key: key,value: value)
}

sender.sendBatchAtomic(data)
```

The above will execute zabbix_sender for you and send data into it as described above.

Alternatively you can just

```ruby
puts data.to_senderinput
```
... and do whatever you want w/ the stdout


To do low level discovery:

```ruby
disco = Zabbix::Discovery.new(key: 'discoveryRuleKey')

disco.add_entity(:SOMEUSEFULVALUE => 'aValue', :ANOTHERONE => 'somethingElse')

data.addDiscovery(disco)

```

### Under the hood

The zabbix-sender cli utility provides a number of methods by which to insert data into zabbix. 

 * zabbix-sender ... -s zabbixHostName -k keyName -o value (one k-v pair at a time)
 * zabbix-sender ... -i - (series of kv pairs from stdin using zabbix-sender start time as timestamp)
 * zabbix-sender ... -T -i - (series of kv pairs with their own embedded timestamps from stdin)

In the latter two cases, the zabbix host name (the name of the host that zabbix is monitoring) is embedded
in the stdin data.

In all cases it is presumed that the zabbix server or proxy to which data should be sent is specified.  This can
be done either by specifying it explicitly with the -z switch, or indirectly by pointing it to a zabbix sender configuration
file with the -c switch.  If you let zabbix_sender_api handle executing zabbix_sender, the target will be specified on the
command line via the -z switch.


zabbix_sender_api utilizes the -T -i - form, so the generated data lines look like this:

```
"theHostBeingMonitored" myFirstKey 1551719379 0
"theHostBeingMonitored" mySecondKey 1551719379 100
```

The above lines will send data to two items associated with the host theHostBeingMonitored: myFirstKey gets the value 0, and mySecondKey gets the value 100.  In both cases the
time stamp is identical but it need not be (see the exe/example.rb for specifics).


Low level discovery (LLD) is also possible with zabbix-sender; the format of the stdin data is not so pretty but zabbix_sender_api handles all that:

```
"theHostBeingMonitored" discoveryRuleKey 1551719797 {"data":[{"{#SOMEUSEFULVALUE}":"aValue","{#ANOTHERONE}":"somethingElse"}]}
```
The above line sends an LLD discovery structure (formatted as json) to the [discovery rule](https://www.zabbix.com/documentation/4.0/manual/discovery/low_level_discovery#discovery_rule) whose key is discoveryRuleKey.  It describes one entity by passing the macro values
#SOMEUSEFULVALUE and #ANOTHERONE to the discovery rule.  These '[lld macros](https://www.zabbix.com/documentation/4.0/manual/config/macros/lld_macros)' are available for use in item,trigger, and graph prototypes.


If you wished to use the above lld to actually do some discovery, you'd set things up in zabbix roughly like this:

![Discovery rule configuration](images/Spectacle.Z29721.png)
![Item prototype configuration](images/Spectacle.l29721.png )