Skip to content

Home

Jump to bottom Edit New page
Kurt edited this page Aug 6, 2015 · 5 revisions

#PyZabbixSender Welcome to the pyZabbixSender wiki!

pyZabbixSender is another Python library to send data from your application to a Zabbix server using "zabbix traps".

The main goal is to have a simple to use tool, compatible with Python 2.5+ (I found some libraries doing similar things, but not compatible with versions prior to 2.6, and that's one of the reasons I started working on this implementation)

Here I'll specify its API to help you start using it, and some extra information to facilitate your work, but first, a small example to show its basic usage:

from pyZabbixSender import pyZabbixSender
z = pyZabbixSender(server="127.0.0.1")
z.addData("test_host", "test_trap1", 21)
z.addData("test_host", "test_trap2", 100.45)
results = z.sendData()
if results[0][0] != z.RC_OK:
    print "ops!", results[0][1]

Important: JSON library availability

Zabbix communication uses json to send/receive data, but older Python versions don't have json available out of the box. If you want to use pyZabbixSender on older Python versions, you can use simplejson. This library is fully compatible with the one that comes in newer Python versions.

#####To use simplejson with older Python versions

  1. Download simplejson from their site.
  2. Extract the content of the package you downloaded anywhere in your file system. Create a symbolic link or rename to remove the version numbers at the end, so the directory name is just "simplejson".
  3. Add the simplejson directory to your PYTHONPATH: export PYTHONPATH=$PYTHONPATH:/your/particular/path/simplejson.

Now edit the file pyZabbixSender.py, uncomment the import simplejson as json and comment the line import json.

You're done. You can start using the library.

##pyZabbixSender API Following you have the API documentation, where method parameters are followed by three elements enclosed by square brackets. In order of appearance, their meanings are:

  1. Specifies if it's input [in], output [out] or input & output [in/out] parameter.
  2. Here you'll see the type expected: integer, string, dict, array, etc. When you found "any", the method will use it in an agnostic way, and if needed, additional information will be provided on its description.
  3. This is to know if that parameter is optional or mandatory. Optional parameters have the default value specified at the end of its own description.

Some methods returns numerical codes to let you know the status of some operations, here's the list of currently available codes:

RC_OK            =   0  # Everything ok
RC_ERR_FAIL_SEND =   1  # Error reported by zabbix when sending data
RC_ERR_PARS_RESP =   2  # Error parsing server response
RC_ERR_CONN      = 255  # Error talking to the server
RC_ERR_INV_RESP  = 254  # Invalid response from server

pyZabbixSender(server, port, verbose)

#####Description: This is the constructor, to obtain an object of type pyZabbixSender, linked to work with a specific server/port.

#####Parameters:

  • server: [in] [string] [optional] This is the server domain name or IP. Default value: "127.0.0.1"
  • port: [in] [integer] [optional] This is the port open in the server to receive zabbix traps. Default value: 10051
  • verbose: [in] [boolean] [optional] This is to allow the library to write some output to stderr when finds an error. Default value: False

Note: The "verbose" parameter will be revisited and could be removed/replaced in the future

#####Return: It returns a pyZabbixSender object.

addData(host, key, value, clock)

#####Description: Adds host, key, value and optionally clock to the internal list of data to be sent later, when calling one of the methods to actually send the data to the server.

#####Parameters:

  • host: [in] [string] [mandatory] The host which the data is associated to.

  • key: [in] [string] [mandatory] The name of the trap associated to the host in the Zabbix server.

  • value: [in] [any] [mandatory] The value you want to send. Please note that you need to take care about the type, as it needs to match key definition in the Zabbix server. Numeric types can be specified as number (for example: 12) or text (for example: "12").

  • clock: [in] [integer] [optional] Here you can specify the Unix timestamp associated to your measurement. For example, you can process a log or a data file produced an hour ago, and you want to send the data with the timestamp when the data was produced, not when it was processed by you. If you don't specify this parameter, zabbix server will assign a timestamp when it receives the data.

    You can create a timestamp compatible with "clock" parameter using this code: int(round(time.time()))

    Default value: None

#####Return: This method doesn't have a return.

clearData()

#####Description: This method removes all data from internal storage. You need to specify when it's done, as it's not automatically done after a data send operation.

#####Parameters: None #####Return: None

getData()

#####Description: This method is used to obtain a copy of the internal data stored in the object.

Please note you will NOT get the internal data object, but a copy of it, so no matter what you do with your copy, internal data will remain safe.

#####Parameters: None #####Return: A copy of the internal data you added using the method addData (an array of dicts).

printData()

#####Description: Print stored data (to stdout), so you can see what will be sent if "sendData" is called. This is useful for debugging purposes.

#####Parameters: None

#####Return: None

removeDataPoint(data_point)

#####Description: This method delete one data point from the internal stored data.

It's main purpose is to narrow the internal data to keep only those failed data points (those that were not received/processed by the server) so you can identify/retry them. Data points can be obtained from sendDataOneByOne return, or from getData return.

#####Parameters:

  • data_point: [in] [dict] [mandatory] This is a dictionary as returned by sendDataOneByOne() or getData methods.

#####Return: It returns True if data_point was found and deleted, and False if not.

sendData(packet_clock, max_data_per_conn)

#####Description: Sends data stored using addData method, to the Zabbix server.

#####Parameters:

  • packet_clock: [in] [integer] [optional] Zabbix server uses the "clock" parameter in the packet to associate that timestamp to all data values not containing their own clock timestamp. Then:
    • If packet_clock is specified, zabbix server will associate it to all data values not containing their own clock.
    • If packet_clock is NOT specified, zabbix server will use the time when it received the packet as packet clock.

You can create a timestamp compatible with "clock" or "packet_clock" parameters using this code:

  int(round(time.time()))

Default value: None

  • max_data_per_conn: [in] [integer] [optional] Allows the user to limit the number of data points sent in one single connection, as some times a too big number can produce problems over slow connections.

    Several "sends" will be automatically performed until all data is sent.

    If omitted, all data points will be sent in one single connection. Default value: None

Please note that internal data is not deleted after sendData is executed. You need to call clearData after sending it, if you want to remove currently stored data.

#####Return: A list of (return_code, msg_from_server) associated to each "send" operation.

sendDataOneByOne()

#####Description: You can use this method to send all stored data, one by one, to determine which traps are not being handled correctly by the server.

Using this method you'll be able to detect things like:

  • hosts not defined in the server
  • traps not defined in some particular host

This is primarily intended for debugging purposes.

#####Parameters: None

#####Return: It returns an array of return codes (one for each individual "send") and the data sent: code_1, data_point_1], [code_2, data_point_2

sendSingle(host, key, value, clock)

#####Description: Instead of storing data for sending later, you can use this method to send specific values right now.

#####Parameters: It shares the same parameters as the addData method.

  • host: [in] [string] [mandatory] The host which the data is associated to.

  • key: [in] [string] [mandatory] The name of the trap associated to the host in the Zabbix server.

  • value: [in] [any] [mandatory] The value you want to send. Please note that you need to take care about the type, as it needs to match key definition in the Zabbix server. Numeric types can be specified as number (for example: 12) or text (for example: "12").

  • clock: [in] [integer] [optional] Here you can specify the Unix timestamp associated to your measurement. For example, you can process a log or a data file produced an hour ago, and you want to send the data with the timestamp when the data was produced, not when it was processed by you. If you don't specify this parameter, zabbix server will assign a timestamp when it receives the data.

    You can create a timestamp compatible with "clock" parameter using this code: int(round(time.time()))

    Default value: None

#####Return: A list containing the return code and the message returned by the server.

sendSingleLikeProxy(self, host, key, value, clock, proxy)

#####Description: Use this method to put the data for host monitored by proxy server. This method emulates proxy protocol and data will be accepted by Zabbix server even if they were send not actually from proxy.

#####Parameters: It shares the same parameters as the addData method, plus another one to specify proxy name.

  • host: [in] [string] [mandatory] The host which the data is associated to.

  • key: [in] [string] [mandatory] The name of the trap associated to the host in the Zabbix server.

  • value: [in] [any] [mandatory] The value you want to send. Please note that you need to take care about the type, as it needs to match key definition in the Zabbix server. Numeric types can be specified as number (for example: 12) or text (for example: "12").

  • clock: [in] [integer] [optional] Here you can specify the Unix timestamp associated to your measurement. For example, you can process a log or a data file produced an hour ago, and you want to send the data with the timestamp when the data was produced, not when it was processed by you. If you don't specify this parameter, zabbix server will assign a timestamp when it receives the data. You can create a timestamp compatible with "clock" parameter using this code: int(round(time.time()))

    Default value: None

  • proxy: [in] [string] [optional] The name of the proxy to be recognized by the Zabbix server. If proxy is not specified, a normal "sendSingle" operation will be performed. Default value: None

#####Return: A list containing the return code and the message returned by the server.

Add a custom footer
Add a custom sidebar
Clone this wiki locally