# Zabbix utils library
[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/tests.yaml)
[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_api.yaml)
[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_sender.yaml)
[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_get.yaml)
[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/compatibility_50.yaml)
[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/compatibility_60.yaml)
[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/compatibility_64.yaml)
**zabbix_utils** is a Python library for working with [Zabbix API](https://www.zabbix.com/documentation/current/manual/api/reference) as well as with [Zabbix sender](https://www.zabbix.com/documentation/current/manpages/zabbix_sender) and [Zabbix get](https://www.zabbix.com/documentation/current/manpages/zabbix_get) protocols.
## Requirements
Supported versions:
* Zabbix 5.0+
* Python 3.8+
Tested on:
* Zabbix 5.0, 6.0, 6.4 and pre-7.0
* Python 3.8, 3.9, 3.10, 3.11 and 3.12
## Documentation
### Installation
Install **zabbix_utils** library using pip:
```bash
$ pip install zabbix_utils
```
### Use cases
##### To work with Zabbix API
To work with Zabbix API you can import and use **zabbix_utils** library as follows:
```python
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()
```
You can also authenticate using an API token (supported since Zabbix 5.4):
```python
from zabbix_utils import ZabbixAPI
api = ZabbixAPI(url="127.0.0.1")
api.login(token="xxxxxxxx")
users = api.user.get(
output=['userid','name']
)
for user in users:
print(user['name'])
```
When token is used, calling `api.logout()` is not necessary.
It is possible to specify authentication fields by the following environment variables:
`ZABBIX_URL`, `ZABBIX_TOKEN`, `ZABBIX_USER`, `ZABBIX_PASSWORD`
You can compare Zabbix API version with strings and numbers, for example:
```python
from zabbix_utils import ZabbixAPI
url = "127.0.0.1"
user = "User"
password = "zabbix"
api = ZabbixAPI(url=url, user=user, password=password)
# Method to get version
ver = api.api_version()
print(type(ver).__name__, ver) # APIVersion 7.0.0
# ZabbixAPI prototype with version
ver = api.version
print(type(ver).__name__, ver) # APIVersion 7.0.0
# Comparing versions
print(ver > 6.0) # True
print(ver != 7.0) # False
print(ver != "7.0.0") # False
# Version additional methods
print(ver.major) # 7.0
print(ver.minor) # 0
print(ver.is_lts()) # True
api.logout()
```
In case the API object or method name matches one of Python keywords, you can use the suffix `_` in their name to execute correctly:
```python
from zabbix_utils import ZabbixAPI
api = ZabbixAPI(url="127.0.0.1")
api.login(token="xxxxxxxx")
template_source = ''
with open('template_example.xml', mode='r', encoding='utf-8') as f:
template_source = f.read()
response = api.configuration.import_(
source=template_source,
format="xml",
rules={...}
)
if response:
print("Template imported successfully")
```
> Please, refer to the [Zabbix API Documentation](https://www.zabbix.com/documentation/current/manual/api/reference) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/main/examples/api) for more information.
##### To work via Zabbix sender protocol
To send item values to a Zabbix server or a Zabbix proxy you can import and use the library as follows:
```python
from zabbix_utils import Sender
sender = Sender(server='127.0.0.1', port=10051)
response = sender.send_value('host', 'item.key', 'value', 1695713666)
print(response)
# {"processed": 1, "failed": 0, "total": 1, "time": "0.000338", "chunk": 1}
```
Or you can prepare a list of item values and send all at once:
```python
from zabbix_utils import ItemValue, Sender
items = [
ItemValue('host1', 'item.key1', 10),
ItemValue('host1', 'item.key2', 'test message'),
ItemValue('host2', 'item.key1', -1, 1695713666),
ItemValue('host3', 'item.key1', '{"msg":"test message"}'),
ItemValue('host2', 'item.key1', 0, 1695713666, 100)
]
sender = Sender(server='127.0.0.1', port=10051)
response = sender.send(items)
print(response)
# {"processed": 5, "failed": 0, "total": 5, "time": "0.001661", "chunk": 1}
```
If you need to send values to several Zabbix clusters at once, you can do this by passing a list of Zabbix clusters:
```python
from zabbix_utils import Sender
zabbix_clusters = [
['zabbix.cluster1.node1', 'zabbix.cluster1.node2:10051'],
['zabbix.cluster2.node1:10051', 'zabbix.cluster2.node2:20051', 'zabbix.cluster2.node3']
]
sender = Sender(clusters=zabbix_clusters)
response = sender.send_value('host', 'item.key', 'value', 1695713666)
print(response)
# {"processed": 2, "failed": 0, "total": 2, "time": "0.000103", "chunk": 2}
print(response.details)
# {
# zabbix.cluster1.node1:10051: [{"processed": 1, "failed": 0, "total": 1, "time": "0.000050", "chunk": 1}],
# zabbix.cluster2.node2:20051: [{"processed": 1, "failed": 0, "total": 1, "time": "0.000053", "chunk": 1}]
# }
```
In such case, the value will be sent to the first available node of each cluster.
> Please, refer to the [Zabbix sender protocol](https://www.zabbix.com/documentation/current/manual/appendix/protocols/zabbix_sender) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/main/examples/sender) for more information.
##### To work via Zabbix get protocol
To get a value by item key from a Zabbix agent or agent 2 you can import and use the library as follows:
```python
from zabbix_utils import Getter
agent = Getter(host='127.0.0.1', port=10050)
resp = agent.get('system.uname')
print(resp.value)
# Linux test_server 5.15.0-3.60.5.1.el9uek.x86_64
```
> Please, refer to the [Zabbix agent protocol](https://www.zabbix.com/documentation/current/manual/appendix/protocols/zabbix_agent) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/main/examples/get) for more information.
### Enabling debug log
If it needed to debug some issue with Zabbix API, sender or get you can enable the output of logging. The **zabbix_utils** library uses the default python logging module, but it doesn't log by default. You can define logging handler to see records from the library, for example:
```python
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)
resp = agent.get('system.uname')
print(resp.value)
```
And then you can see records like the following:
```
[2023-10-01 12:00:01,587] DEBUG Content of the packet: b'ZBXD\x01\x0c\x00\x00\x00\x00\x00\x00\x00system.uname'
[2023-10-01 12:00:01,722] DEBUG Zabbix response header: b'ZBXD\x01C\x00\x00\x00C\x00\x00\x00'
[2023-10-01 12:00:01,723] DEBUG Zabbix response body: Linux test_server 5.15.0-3.60.5.1.el9uek.x86_64
[2023-10-01 12:00:01,724] DEBUG Response from [127.0.0.1:10050]: Linux test_server 5.15.0-3.60.5.1.el9uek.x86_64
Linux test_server 5.15.0-3.60.5.1.el9uek.x86_64
```
## License
**zabbix_utils** is distributed under MIT License.
Raw data
{
"_id": null,
"home_page": "https://github.com/zabbix/python-zabbix-utils",
"name": "zabbix-utils",
"maintainer": "Aleksandr Iantsen",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "aleksandr.iantsen@zabbix.com",
"keywords": "monitoring zabbix api sender get utils tools",
"author": "Zabbix SIA",
"author_email": "integrationteam@zabbix.com",
"download_url": "https://files.pythonhosted.org/packages/4d/ae/0445588064ad8beba5c73a5a51a18e55d73dabca535c25d14f333e6ab04a/zabbix_utils-1.1.1.tar.gz",
"platform": null,
"description": "# Zabbix utils library\r\n\r\n[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/tests.yaml)\r\n[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_api.yaml)\r\n[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_sender.yaml)\r\n[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/integration_get.yaml)\r\n[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/compatibility_50.yaml)\r\n[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/compatibility_60.yaml)\r\n[](https://github.com/zabbix/python-zabbix-utils/actions/workflows/compatibility_64.yaml)\r\n\r\n**zabbix_utils** is a Python library for working with [Zabbix API](https://www.zabbix.com/documentation/current/manual/api/reference) as well as with [Zabbix sender](https://www.zabbix.com/documentation/current/manpages/zabbix_sender) and [Zabbix get](https://www.zabbix.com/documentation/current/manpages/zabbix_get) protocols.\r\n\r\n## Requirements\r\n\r\nSupported versions:\r\n\r\n* Zabbix 5.0+\r\n* Python 3.8+\r\n\r\nTested on:\r\n\r\n* Zabbix 5.0, 6.0, 6.4 and pre-7.0\r\n* Python 3.8, 3.9, 3.10, 3.11 and 3.12\r\n\r\n## Documentation\r\n\r\n### Installation\r\n\r\nInstall **zabbix_utils** library using pip:\r\n\r\n```bash\r\n$ pip install zabbix_utils\r\n```\r\n\r\n### Use cases\r\n\r\n##### To work with Zabbix API\r\n\r\nTo work with Zabbix API you can import and use **zabbix_utils** library as follows:\r\n\r\n```python\r\nfrom zabbix_utils import ZabbixAPI\r\n\r\napi = ZabbixAPI(url=\"127.0.0.1\")\r\napi.login(user=\"User\", password=\"zabbix\")\r\n\r\nusers = api.user.get(\r\n output=['userid','name']\r\n)\r\n\r\nfor user in users:\r\n print(user['name'])\r\n\r\napi.logout()\r\n```\r\n\r\nYou can also authenticate using an API token (supported since Zabbix 5.4):\r\n\r\n```python\r\nfrom zabbix_utils import ZabbixAPI\r\n\r\napi = ZabbixAPI(url=\"127.0.0.1\")\r\napi.login(token=\"xxxxxxxx\")\r\n\r\nusers = api.user.get(\r\n output=['userid','name']\r\n)\r\n\r\nfor user in users:\r\n print(user['name'])\r\n```\r\n\r\nWhen token is used, calling `api.logout()` is not necessary.\r\n\r\nIt is possible to specify authentication fields by the following environment variables:\r\n`ZABBIX_URL`, `ZABBIX_TOKEN`, `ZABBIX_USER`, `ZABBIX_PASSWORD`\r\n\r\nYou can compare Zabbix API version with strings and numbers, for example:\r\n\r\n```python\r\nfrom zabbix_utils import ZabbixAPI\r\n\r\nurl = \"127.0.0.1\"\r\nuser = \"User\"\r\npassword = \"zabbix\"\r\n\r\napi = ZabbixAPI(url=url, user=user, password=password)\r\n\r\n# Method to get version\r\nver = api.api_version()\r\nprint(type(ver).__name__, ver) # APIVersion 7.0.0\r\n\r\n# ZabbixAPI prototype with version\r\nver = api.version\r\nprint(type(ver).__name__, ver) # APIVersion 7.0.0\r\n\r\n# Comparing versions\r\nprint(ver > 6.0) # True\r\nprint(ver != 7.0) # False\r\nprint(ver != \"7.0.0\") # False\r\n\r\n# Version additional methods\r\nprint(ver.major) # 7.0\r\nprint(ver.minor) # 0\r\nprint(ver.is_lts()) # True\r\n\r\napi.logout()\r\n```\r\n\r\nIn case the API object or method name matches one of Python keywords, you can use the suffix `_` in their name to execute correctly:\r\n```python\r\nfrom zabbix_utils import ZabbixAPI\r\n\r\napi = ZabbixAPI(url=\"127.0.0.1\")\r\napi.login(token=\"xxxxxxxx\")\r\n\r\ntemplate_source = ''\r\nwith open('template_example.xml', mode='r', encoding='utf-8') as f:\r\n template_source = f.read()\r\n\r\nresponse = api.configuration.import_(\r\n source=template_source,\r\n format=\"xml\",\r\n rules={...}\r\n)\r\n\r\nif response:\r\n print(\"Template imported successfully\")\r\n```\r\n\r\n> Please, refer to the [Zabbix API Documentation](https://www.zabbix.com/documentation/current/manual/api/reference) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/main/examples/api) for more information.\r\n\r\n##### To work via Zabbix sender protocol\r\n\r\nTo send item values to a Zabbix server or a Zabbix proxy you can import and use the library as follows:\r\n\r\n```python\r\nfrom zabbix_utils import Sender\r\n\r\nsender = Sender(server='127.0.0.1', port=10051)\r\nresponse = sender.send_value('host', 'item.key', 'value', 1695713666)\r\n\r\nprint(response)\r\n# {\"processed\": 1, \"failed\": 0, \"total\": 1, \"time\": \"0.000338\", \"chunk\": 1}\r\n```\r\n\r\nOr you can prepare a list of item values and send all at once:\r\n\r\n```python\r\nfrom zabbix_utils import ItemValue, Sender\r\n\r\nitems = [\r\n ItemValue('host1', 'item.key1', 10),\r\n ItemValue('host1', 'item.key2', 'test message'),\r\n ItemValue('host2', 'item.key1', -1, 1695713666),\r\n ItemValue('host3', 'item.key1', '{\"msg\":\"test message\"}'),\r\n ItemValue('host2', 'item.key1', 0, 1695713666, 100)\r\n]\r\n\r\nsender = Sender(server='127.0.0.1', port=10051)\r\nresponse = sender.send(items)\r\n\r\nprint(response)\r\n# {\"processed\": 5, \"failed\": 0, \"total\": 5, \"time\": \"0.001661\", \"chunk\": 1}\r\n```\r\n\r\nIf you need to send values to several Zabbix clusters at once, you can do this by passing a list of Zabbix clusters:\r\n\r\n```python\r\nfrom zabbix_utils import Sender\r\n\r\nzabbix_clusters = [\r\n ['zabbix.cluster1.node1', 'zabbix.cluster1.node2:10051'],\r\n ['zabbix.cluster2.node1:10051', 'zabbix.cluster2.node2:20051', 'zabbix.cluster2.node3']\r\n]\r\n\r\nsender = Sender(clusters=zabbix_clusters)\r\nresponse = sender.send_value('host', 'item.key', 'value', 1695713666)\r\n\r\nprint(response)\r\n# {\"processed\": 2, \"failed\": 0, \"total\": 2, \"time\": \"0.000103\", \"chunk\": 2}\r\n\r\nprint(response.details)\r\n# {\r\n# zabbix.cluster1.node1:10051: [{\"processed\": 1, \"failed\": 0, \"total\": 1, \"time\": \"0.000050\", \"chunk\": 1}],\r\n# zabbix.cluster2.node2:20051: [{\"processed\": 1, \"failed\": 0, \"total\": 1, \"time\": \"0.000053\", \"chunk\": 1}]\r\n# }\r\n```\r\n\r\nIn such case, the value will be sent to the first available node of each cluster.\r\n\r\n> Please, refer to the [Zabbix sender protocol](https://www.zabbix.com/documentation/current/manual/appendix/protocols/zabbix_sender) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/main/examples/sender) for more information.\r\n\r\n##### To work via Zabbix get protocol\r\n\r\nTo get a value by item key from a Zabbix agent or agent 2 you can import and use the library as follows:\r\n\r\n```python\r\nfrom zabbix_utils import Getter\r\n\r\nagent = Getter(host='127.0.0.1', port=10050)\r\nresp = agent.get('system.uname')\r\n\r\nprint(resp.value)\r\n# Linux test_server 5.15.0-3.60.5.1.el9uek.x86_64\r\n```\r\n\r\n> Please, refer to the [Zabbix agent protocol](https://www.zabbix.com/documentation/current/manual/appendix/protocols/zabbix_agent) and the [using examples](https://github.com/zabbix/python-zabbix-utils/tree/main/examples/get) for more information.\r\n\r\n### Enabling debug log\r\n\r\nIf it needed to debug some issue with Zabbix API, sender or get you can enable the output of logging. The **zabbix_utils** library uses the default python logging module, but it doesn't log by default. You can define logging handler to see records from the library, for example:\r\n\r\n```python\r\nimport logging\r\nfrom zabbix_utils import Getter\r\n\r\nlogging.basicConfig(\r\n format=u'[%(asctime)s] %(levelname)s %(message)s',\r\n level=logging.DEBUG\r\n)\r\n\r\nagent = Getter(host='127.0.0.1', port=10050)\r\nresp = agent.get('system.uname')\r\n\r\nprint(resp.value)\r\n```\r\n\r\nAnd then you can see records like the following:\r\n\r\n```\r\n[2023-10-01 12:00:01,587] DEBUG Content of the packet: b'ZBXD\\x01\\x0c\\x00\\x00\\x00\\x00\\x00\\x00\\x00system.uname'\r\n[2023-10-01 12:00:01,722] DEBUG Zabbix response header: b'ZBXD\\x01C\\x00\\x00\\x00C\\x00\\x00\\x00'\r\n[2023-10-01 12:00:01,723] DEBUG Zabbix response body: Linux test_server 5.15.0-3.60.5.1.el9uek.x86_64\r\n[2023-10-01 12:00:01,724] DEBUG Response from [127.0.0.1:10050]: Linux test_server 5.15.0-3.60.5.1.el9uek.x86_64\r\nLinux test_server 5.15.0-3.60.5.1.el9uek.x86_64\r\n\r\n```\r\n\r\n## License\r\n**zabbix_utils** is distributed under MIT License.\r\n",
"bugtrack_url": null,
"license": "",
"summary": "A library with modules for working with Zabbix (Zabbix API, Zabbix sender, Zabbix get)",
"version": "1.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/zabbix/python-zabbix-utils/issues",
"Changes": "https://github.com/zabbix/python-zabbix-utils/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/zabbix/python-zabbix-utils",
"Source": "https://github.com/zabbix/python-zabbix-utils",
"Zabbix": "https://www.zabbix.com/documentation/current"
},
"split_keywords": [
"monitoring",
"zabbix",
"api",
"sender",
"get",
"utils",
"tools"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "38194519cc9a0b31a6a23973b69437197439c5572b443ee20d71b277ed240d87",
"md5": "f44b0de3bf7d7d685310400a34805799",
"sha256": "68783c69ae764f1b62f2e5721b9a741ead1f950318ae96e77731553018a32972"
},
"downloads": -1,
"filename": "zabbix_utils-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f44b0de3bf7d7d685310400a34805799",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 24396,
"upload_time": "2024-03-06T11:40:19",
"upload_time_iso_8601": "2024-03-06T11:40:19.417297Z",
"url": "https://files.pythonhosted.org/packages/38/19/4519cc9a0b31a6a23973b69437197439c5572b443ee20d71b277ed240d87/zabbix_utils-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4dae0445588064ad8beba5c73a5a51a18e55d73dabca535c25d14f333e6ab04a",
"md5": "7cae3ea472c0b27fed501524f7ebce4b",
"sha256": "5a3d84832e9f5aa3777c702da3b23980b334fb185d4d95dd68ee800b0fb40cd8"
},
"downloads": -1,
"filename": "zabbix_utils-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "7cae3ea472c0b27fed501524f7ebce4b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19183,
"upload_time": "2024-03-06T11:40:20",
"upload_time_iso_8601": "2024-03-06T11:40:20.983804Z",
"url": "https://files.pythonhosted.org/packages/4d/ae/0445588064ad8beba5c73a5a51a18e55d73dabca535c25d14f333e6ab04a/zabbix_utils-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-06 11:40:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zabbix",
"github_project": "python-zabbix-utils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zabbix-utils"
}
JSON
