Docs

In synchronous mode, your Python script requests and waits for data before continuing, which is suitable for simple, sequential, and predictable operations.
In asynchronous mode, the script requests data without waiting for each response, allowing other operations to proceed in parallel; this is more efficient for slow requests or large batches of data.

The examples on this page focus on synchronous mode, though asynchronous mode follows similar patterns. Additional examples are available in the zabbix_utils GitHub repository.

Import

To use zabbix_utils for collecting item values, import the Getter class in your Python script:

from zabbix_utils import Getter

Request data

To request an item value:

Create a Getter instance, specifying the IP address and port of your Zabbix agent.
Call the get() method on the Getter instance, specifying the key of the item you want to retrieve.

For example, to request data for the system.uname item:

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

Using non-default IP

If the server running your script has multiple IP addresses, you can specify a source_ip for the Getter to use when connecting to Zabbix agent:

agent = Getter(
    host='192.0.2.0',
    port=10050,
    source_ip='10.10.7.1'
)

Using timeout

You can set a response timeout for the Getter to control how long your script should wait for a response from Zabbix agent before giving up:

agent = Getter(
    host='192.0.2.0',
    port=10050,
    timeout=30
)

Using encryption

The Getter does not include built-in encryption support, but you can provide it by creating a wrapper using third-party libraries:

def psk_wrapper(sock, tls):
    # ...
    # Implementation of TLS PSK wrapper for the socket
    # ...

agent = Getter(
    host='192.0.2.0',
    port=10050,
    socket_wrapper=psk_wrapper
)

Response

The response from Zabbix agent is processed by the library and returned as an AgentResponse object:

print(response)
# {
#     "error": null,
#     "raw": "Linux zabbix_server 5.15.0-3.60.5.1.el9uek.x86_64",
#     "value": "Linux zabbix_server 5.15.0-3.60.5.1.el9uek.x86_64"
# }

print(response.value)
# Linux zabbix_server 5.15.0-3.60.5.1.el9uek.x86_64

print(response.error)
# None

Asynchronous mode

Asynchronous mode lets your script collect values without waiting for each one to arrive. This can make your script more efficient when it needs to collect many values or when some values take a long time to be collected.

When using asynchronous mode, there are important differences compared to synchronous mode:

Import Python's asyncio module (you must first install the required dependencies).
Import AsyncGetter instead of Getter.
Write your code inside an async function.
Use await when calling the get() method.

For example, to collect a single value using asynchronous mode:

# 1. Import asyncio for asynchronous mode, and AsyncGetter from zabbix_utils:
import asyncio
from zabbix_utils import AsyncGetter

# 2. Define the main async function where all data requests will be executed:
async def main():
    agent = AsyncGetter(host='192.0.2.0', port=10050)

    # 3. Fetch the system.uname value from Zabbix agent (must await):
    response = await agent.get('system.uname')

    # 4. Print the value returned by Zabbix agent:
    print(response.value)

# 5. Run the async main() function using asyncio's event loop:
asyncio.run(main())

What’s next?

Send data to Zabbix server or proxy

Docs

Collect data from Zabbix agent

Overview