Zabbix Utils

Common errors

• zabbix_utils.exceptions.ProcessingError: Unexpected response was received from Zabbix.

  cause This error typically indicates that the Zabbix server responded with something unexpected or invalid, often due to misconfiguration, network issues, or the Zabbix server being unavailable or returning an error status.
  fix Verify that the Zabbix server URL is correct, the Zabbix API is accessible, and the server is running. Check Zabbix server logs for any related errors.

• The connection to zabbixsrv.example.net:10051 timed out after 10 seconds while trying to send.

  cause This indicates a network connectivity issue or that the Zabbix server/proxy is not listening on the specified host and port (default 10051 for sender). A firewall might also be blocking the connection.
  fix Ensure the Zabbix server/proxy is running, the host and port are correct, and no firewalls are blocking the connection between your script and the Zabbix server/proxy. Consider increasing the timeout if latency is expected.

• Zabbix API version mismatch. The Zabbix server version (X.Y) is not officially supported by this library version (A.B).

  cause Your `zabbix-utils` library version does not officially support the Zabbix server version you are trying to connect to. This can happen when a new Zabbix server version is released before the library is updated.
  fix Upgrade `zabbix-utils` to the latest version (`pip install --upgrade zabbix-utils`). If the latest version still doesn't support your Zabbix server, you might need to use the `skip_version_check=True` parameter in `ZabbixAPI` (use with caution) or wait for a library update.

Warnings

• breaking The format of responses from the `Sender` and `Getter` classes changed significantly in version 1.1.0. Existing code parsing these responses will break.
  Fix: Review the new response format for `Sender` and `Getter` methods and update parsing logic accordingly. Refer to official documentation or examples for the new structure.
• breaking Version 2.0.0 introduced asynchronous modules (`AsyncZabbixAPI`, `AsyncSender`, `AsyncGetter`). While synchronous modules still exist, users migrating to async will need to rewrite their code using `await` and an async event loop.
  Fix: For asynchronous operations, import `AsyncZabbixAPI` (or `AsyncSender`, `AsyncGetter`), define an `async` function, and `await` all API calls. Install `aiohttp` for async dependencies.
• breaking Support for HTTP authentication was discontinued for Zabbix server versions 7.2 and newer starting from `zabbix-utils` version 2.0.2.
  Fix: Upgrade your Zabbix server to use API tokens for authentication or downgrade `zabbix-utils` if compatible with your Zabbix server version and prior authentication methods.
• deprecated Official support for Zabbix server version 5.0 was discontinued with the release of `zabbix-utils` version 2.0.3.
  Fix: It is highly recommended to upgrade your Zabbix server to a currently supported version to ensure compatibility and receive security updates.
• gotcha Zabbix API methods with names that are Python keywords (e.g., `import`, `get`) require an underscore suffix when called through the `ZabbixAPI` object to avoid syntax errors.
  Fix: When calling such methods, append an underscore. For example, `api.configuration.import_()` instead of `api.configuration.import()`.
• gotcha A bug causing timeout parameters to be ignored for connections was fixed in version 2.0.4, which could lead to scripts hanging indefinitely on network issues in older versions.
  Fix: Upgrade to `zabbix-utils` version 2.0.4 or newer to ensure connection timeouts are respected and prevent scripts from hanging.

Install

• pip install zabbix-utils Install stable version
• pip install zabbix-utils[async] Install with asynchronous dependencies

Imports

• ZabbixAPI

  from zabbix_utils import ZabbixAPI

  For synchronous interaction with the Zabbix API.
• AsyncZabbixAPI

  from zabbix_utils import AsyncZabbixAPI

  For asynchronous interaction with the Zabbix API, requiring an async event loop.
• Sender

  from zabbix_utils import Sender

  For sending data to Zabbix server or proxy, similar to zabbix_sender utility.
• Getter

  from zabbix_utils import Getter

  For retrieving data from Zabbix agents, similar to zabbix_get utility.

Quickstart

This quickstart demonstrates how to establish a connection to the Zabbix API using `ZabbixAPI` class, authenticate with username and password (or token), and perform a basic API call to retrieve a list of hosts. It prioritizes environment variables for credentials, falling back to defaults if not set. Remember to replace placeholder values with your actual Zabbix server URL and credentials. For asynchronous operations, use `AsyncZabbixAPI` and `await` with an `async def` function.

import os
from zabbix_utils import ZabbixAPI

# Configure Zabbix API access using environment variables
ZABBIX_URL = os.environ.get('ZABBIX_URL', 'http://127.0.0.1/zabbix')
ZABBIX_USER = os.environ.get('ZABBIX_USER', 'Admin')
ZABBIX_PASSWORD = os.environ.get('ZABBIX_PASSWORD', 'zabbix')

# Initialize ZabbixAPI instance and log in
try:
    api = ZabbixAPI(url=ZABBIX_URL)
    api.login(user=ZABBIX_USER, password=ZABBIX_PASSWORD)
    print(f"Successfully logged into Zabbix API at {ZABBIX_URL}")

    # Example: Fetch all hosts
    hosts = api.host.get(output=['hostid', 'name'])
    if hosts:
        print("\nKnown hosts:")
        for host in hosts:
            print(f"  ID: {host['hostid']}, Name: {host['name']}")
    else:
        print("No hosts found.")

except Exception as e:
    print(f"Error connecting to Zabbix API: {e}")
finally:
    # Always log out to close the session if logged in
    if 'api' in locals() and api.is_logged_in:
        api.logout()
        print("Logged out from Zabbix API.")