DOCSEARCHbyAlgolia
Submit Docs

zabbix_utils Python Library

repository·main·Indexed 42 days ago

https://github.com/zabbix/python-zabbix-utils

A Python library for interacting with Zabbix via its API, Zabbix Sender protocol, and Zabbix Get protocol. Supports both synchronous and asynchronous (asyncio) workflows using ZabbixAPI, AsyncZabbixAPI, Sender, AsyncSender, Getter, and AsyncGetter.

Tokens
1.8K
Snippets
8
Records
8
Agent score
3%

What's inside zabbix-utils

  1. Install zabbix_utils from Zabbix repositories

    main

    You can install official packages via system package managers if you have the Zabbix repository configured.

    Red Hat Enterprise Linux and derivatives: Use dnf. To enable asynchronous support, install epel-release and python3-aiohttp.

    Debian / Ubuntu and derivatives: Use apt. To enable asynchronous support, install python3-aiohttp.

    # RHEL/derivatives
# dnf install python3-zabbix-utils
# dnf install epel-release
# dnf install python3-aiohttp

# Debian/Ubuntu
# apt install python3-zabbix-utils
# apt install python3-aiohttp

  2. Install zabbix_utils via pip

    main

    Install the zabbix_utils library using pip. For asynchronous support, you must install the [async] extra to include aiohttp.

    # Standard installation
$ pip install zabbix_utils

# Installation with async dependencies (aiohttp)
$ pip install zabbix_utils[async]

  4. Enable debug logging for zabbix_utils

    main

    The library uses the standard Python logging module but does not log by default. To debug API, Sender, or Get issues, configure a logging handler with level=logging.DEBUG.

    import logging
from zabbix_utils import Getter

logging.basicConfig(
    format=u'[%(asctime)s] %(levelname)s %(message)s',
    level=logging.DEBUG
)

agent = Getter(host='127.0.0.1', port=10050)
agent.get('system.uname')

  5. Use the Zabbix API (Synchronous and Asynchronous)

    main

    Use ZabbixAPI for synchronous I/O or AsyncZabbixAPI for asynchronous I/O.

    Authentication:

    • Use .login(user='...', password='...') for username/password.
    • Use .login(token='...') for API tokens (supported since Zabbix 5.4). When using a token, .logout() is not required.
    • Authentication can also be configured via environment variables: ZABBIX_URL, ZABBIX_TOKEN, ZABBIX_USER, ZABBIX_PASSWORD.

    Handling Python Keywords: If an API method name matches a Python keyword (e.g., import), use the suffix _ (e.g., api.configuration.import_()).

    # Synchronous Example
from zabbix_utils import ZabbixAPI

api = ZabbixAPI(url="127.0.0.1")
api.login(user="User", password="zabbix")
users = api.user.get(output=['userid','name'])
for user in users:
    print(user['name'])
api.logout()

# Asynchronous Example
import asyncio
from zabbix_utils import AsyncZabbixAPI

async def main():
    api = AsyncZabbixAPI(url="127.0.0.1")
    await api.login(token="xxxxxxxx")
    users = await api.user.get(output=['userid','name'])
    for user in users:
        print(user['name'])

asyncio.run(main())

  6. Compare Zabbix API versions

    main

    The api.api_version() method or the api.version property returns an APIVersion object. This object supports comparison with strings, numbers, and other APIVersion objects. It also provides metadata like .major, .minor, and .is_lts().

    # Get version object
ver = api.api_version() 

# Comparisons
print(ver > 6.0)      # True
print(ver != 7.0)     # False
print(ver != "7.0.0") # False

# Metadata
print(ver.major)    # 7.0
print(ver.minor)    # 0
print(ver.is_lts()) # True

  7. Use the Zabbix Get protocol

    main

    Use Getter (sync) or AsyncGetter (async) to retrieve values from a Zabbix agent or agent 2 via item key.

    # Synchronous
from zabbix_utils import Getter
agent = Getter(host='127.0.0.1', port=10050)
resp = agent.get('system.uname')
print(resp.value)

# Asynchronous
import asyncio
from zabbix_utils import AsyncGetter

async def main():
    agent = AsyncGetter(host='127.0.0.1', port=10050)
    resp = await agent.get('system.uname')
    print(resp.value)

asyncio.run(main())

  8. Use the Zabbix Sender protocol

    main

    Use Sender (sync) or AsyncSender (async) to send item values to a Zabbix server or proxy.

    Key Features:

    • Single value: Use .send_value(host, item_key, value, timestamp).
    • Bulk sending: Create a list of ItemValue objects and use .send(items).
    • Clusters: Pass a list of clusters to the Sender(clusters=...) constructor. The value will be sent to the first available node in each cluster. The response includes a .details attribute mapping results to each cluster node.
    from zabbix_utils import Sender, ItemValue

# Single value
sender = Sender(server='127.0.0.1', port=10051)
response = sender.send_value('host', 'item.key', 'value', 1695713666)

# Bulk values
items = [
    ItemValue('host1', 'item.key1', 10),
    ItemValue('host2', 'item.key1', 'test message')
]
sender.send(items)

# Clusters
zabbix_clusters = [
    ['node1', 'node2:10051'],
    ['node3:10051', 'node4:20051']
]
sender = Sender(clusters=zabbix_clusters)
sender.send_value('host', 'item.key', 'value')