python-protobix

dev Branch:
upstream Branch (default):

python-protobix is a very simple python module which implements Zabbix Sender protocol 2.0.
It allows to build a list of Zabbix items and send them as trappers.

Currently python-protobix supports "classics" items as well as Low Level Discovery ones.

Please note that python-protobix is developped and tested on Debian GNU/Linux only.
I can't enforce compatibility with other distributions, though it should work on any distribution providing Python 2.7 or Python 3.x.

Any feedback on this is, of course, welcomed.

Test

To install all required dependencies and launch test suite

python setup.py test

By default, all tests named like *need_backend* are disabled, since they need a working Zabbix Server.

If you want to run theses tests as well, you will need:

a working Zabbix Server 3.x configuration file like the one in tests/zabbix/zabbix_server.conf
SQL statements in tests/zabbix/zabbix_server_mysql.sql with all informations to create testing hosts & items

You can then start Zabbix Server with zabbix_server -c tests/zabbix/zabbix_server.conf -f and launch test suite with

py.test --cov protobix --cov-report term-missing

Using a docker container

You can also use docker to run test suite on any Linux distribution of your choice.
You can use provided script docker-tests.sh as entrypoint example:

docker run --volume=$(pwd):/home/python-protobix --entrypoint=/home/python-protobix/tests/docker-tests.sh -ti debian:jessie

Currently, entrypoint docker-tests.sh only supports Debian GNU/Linux.

Please note that this docker entrypoint does not provide a way to execute test that need a backend.

Installation

With pip (stable version):

pip install protobix

With pip (test version):

pip install -i https://testpypi.python.org/simple/ protobix

Python is available as Debian package for Debian GNU/Linux sid and testing.

Usage

Once module is installed, you can use it either extending protobix.SampleProbe or directly using protobix.Datacontainer.

Extend `protobix.SampleProbe`

python-protobix provides a convenient sample probe you can extend to fit your own needs.

Using protobix.SampleProbe allows you to concentrate on getting metrics or Low Level Discovery items without taking care of anything related to protobix itself.
This is the recommanded way of using python-protobix.

protobix.SampleProbe provides a run method which take care of everything related to protobix.

Some probes are available from my Github repository python-zabbix

#!/usr/bin/env python
# -*- coding: utf-8 -*-
''' Copyright (c) 2013 Jean Baptiste Favre.
    Sample Python class which extends protobix.SampleProbe
'''
import protobix
import argparse
import socket
import sys

class ExampleProbe(protobix.SampleProbe):

    __version__ = '1.0.2'
    # discovery_key is *not* the one declared in Zabbix Agent configuration
    # it's the one declared in Zabbix template's "Discovery rules"
    discovery_key = "example.probe.llddiscovery"

    def _parse_probe_args(self, parser):
        # Parse the script arguments
        # parser is an instance of argparse.parser created by SampleProbe._parse_args method
        # you *must* return parser to SampleProbe so that your own options are taken into account
        example_probe_options = parser.add_argument_group('ExampleProbe configuration')
        example_probe_options.add_argument(
            "-o", "--option", default="default_value",
            help="WTF do this option"
        )
        return parser

    def _init_probe(self):
        # Whatever you need to initiliaze your probe
        # Can be establishing a connection
        # Or reading a configuration file
        # If you have nothing special to do
        # Just do not override this method
        # Or use:
        pass

    def _get_discovery(self):
        # Whatever you need to do to discover LLD items
        # this method is mandatory
        # If not declared, calling the probe ith --discovery option will resut in a NotimplementedError
        # If you get discovery infos for only one node you should return data as follow
        return { self.hostname: data }
        # If you get discovery infos for many hosts, then you should build data dict by yourself
        # and return result as follow
        return data

    def _get_metrics(self):
        # Whatever you need to do to collect metrics
        # this method is mandatory
        # If not declared, calling the probe with --update-items option will resut in a NotimplementedError
        # If you get metrics for only one node you should return data as follow
        return { self.hostname: data }
        # If you get metrics for many hosts, then you should build data dict by your self
        # and return result as follow
        return data

if __name__ == '__main__':
    ret = RedisServer().run()
    print ret
    sys.exit(ret)

Declare your newly created probe as Zabbix Agent user parameters:

UserParameter=example.probe.check,/usr/local/bin/example_probe.py --update-items
UserParameter=example.probe.discovery,/usr/local/bin/example_probe.py --discovery

You're done.

The protobix.SampleProbe exit code will be sent to Zabbix.
You'll be able to setup triggers if needed.

Exit codes mapping:

0: everything went well
1: probe failed at step 1 (probe initialization)
2: probe failed at step 2 (probe data collection)
3: probe failed at step 3 (add data to DataContainer)
4: probe failed at step 4 (send data to Zabbix)

Use `protobix.Datacontainer`

If you don't want or can't use protobix.SampleProbe, you can also directly use protobix.Datacontainer.

How to send items updates

#!/usr/bin/env python

''' import module '''
import protobix

DATA = {
    "protobix.host1": {
        "my.protobix.item.int": 0,
        "my.protobix.item.string": "item string"
    },
    "protobix.host2": {
        "my.protobix.item.int": 0,
        "my.protobix.item.string": "item string"
    }
}

zbx_datacontainer = protobix.DataContainer()
zbx_datacontainer.data_type = 'items'
zbx_datacontainer.add(DATA)
zbx_datacontainer.send()

How to send Low Level Discovery

#!/usr/bin/env python

''' import module '''
import protobix

DATA = {
    'protobix.host1': {
        'my.protobix.lld_item1': [
            { '{#PBX_LLD_KEY11}': 0,
              '{#PBX_LLD_KEY12}': 'lld string' },
            { '{#PBX_LLD_KEY11}': 1,
              '{#PBX_LLD_KEY12}': 'another lld string' }
        ],
        'my.protobix.lld_item2': [
            { '{#PBX_LLD_KEY21}': 10,
              '{#PBX_LLD_KEY21}': 'yet an lld string' },
            { '{#PBX_LLD_KEY21}': 2,
              '{#PBX_LLD_KEY21}': 'yet another lld string' }
        ]
    },
    'protobix.host2': {
        'my.protobix.lld_item1': [
            { '{#PBX_LLD_KEY11}': 0,
              '{#PBX_LLD_KEY12}': 'lld string' },
            { '{#PBX_LLD_KEY11}': 1,
              '{#PBX_LLD_KEY12}': 'another lld string' }
        ],
        'my.protobix.lld_item2': [
            { '{#PBX_LLD_KEY21}': 10,
              '{#PBX_LLD_KEY21}': 'yet an lld string' },
            { '{#PBX_LLD_KEY21}': 2,
              '{#PBX_LLD_KEY21}': 'yet another lld string' }
        ]
    }
}

zbx_datacontainer = protobix.DataContainer()
zbx_datacontainer.data_type = 'lld'
zbx_datacontainer.add(DATA)
zbx_datacontainer.send()

Advanced configuration

python-protobix behaviour can be altered in many ways using options.
All configuration options are stored in a protobix.ZabbixAgentConfig instance.

Protobix specific configuration options

Option name	Default value	ZabbixAgentConfig property	Command-line option (SampleProbe)
`data_type`	`None`	`data_type`	`--update-items` or `--discovery`
`dryrun`	`False`	`dryrun`	`-d` or `--dryrun`

Zabbix Agent configuration options

Option name	Default value	ZabbixAgentConfig property	Command-line option (SampleProbe)
`ServerActive`	`127.0.0.1`	`server_active`	`-z` or `--zabbix-server`
`ServerPort`	`10051`	`server_port`	`-p` or `--port`
`LogType`	`file`	`log_type`	none
`LogFile`	`/tmp/zabbix_agentd.log`	`log_file`	none
`DebugLevel`	`3`	`debug_level`	`-v` (from none to `-vvvvv`)
`Timeout`	`3`	`timeout`	none
`Hostname`	`socket.getfqdn()`	`hostname`	none
`TLSConnect`	`unencrypted`	`tls_connect`	`--tls-connect`
`TLSCAFile`	`None`	`tls_ca_file`	`--tls-ca-file`
`TLSCertFile`	`None`	`tls_cert_file`	`--tls-cert-file`
`TLSCRLFile`	`None`	`tls_crl_file`	`--tls-crl-file`
`TLSKeyFile`	`None`	`tls_key_file`	`--tls-key-file`
`TLSServerCertIssuer`	`None`	`tls_server_cert_issuer`	`--tls-server-cert-issuer`
`TLSServerCertSubject`	`None`	`tls_server_cert_subject`	`--tls-server-cert-subject`

How to contribute

You can contribute to protobix:

fork this repository
write tests and documentation (tests must pass for both Python 2.7 & 3.x)
implement the feature you need
open a pull request against upstream branch

duanshuaimin / python-protobix

python-protobix

Test

Using a docker container

Installation

Usage

Extend `protobix.SampleProbe`

Use `protobix.Datacontainer`

Advanced configuration

How to contribute

About

Languages

python-protobix

Test

Using a docker container

Installation

Usage

Extend protobix.SampleProbe

Use protobix.Datacontainer

Advanced configuration

How to contribute

About

Languages

Extend `protobix.SampleProbe`

Use `protobix.Datacontainer`