0
# py-zabbix
1

2
A comprehensive Python module to work with Zabbix monitoring systems through both API and sender functionality. It provides a ZabbixAPI class for authentication and performing various operations like host management, data retrieval, and configuration changes through Zabbix's JSON-RPC API, plus ZabbixSender functionality for pushing metrics data to Zabbix trappers.
3

4
## Package Information
5

6
- **Package Name**: py-zabbix
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install py-zabbix`
10

11
## Core Imports
12

13
```python
14
from pyzabbix import ZabbixAPI, ZabbixAPIException, ZabbixMetric, ZabbixSender, ZabbixResponse, ssl_context_compat
15
```
16

17
Specific module imports:
18

19
```python
20
from pyzabbix.api import ZabbixAPI, ZabbixAPIException, ssl_context_compat
21
from pyzabbix.sender import ZabbixMetric, ZabbixSender, ZabbixResponse
22
```
23

24
## Basic Usage
25

26
### API Interaction
27

28
```python
29
from pyzabbix import ZabbixAPI
30

31
# Create ZabbixAPI instance and authenticate
32
zapi = ZabbixAPI(url='https://zabbix.example.com', user='Admin', password='zabbix')
33

34
# Get all monitored hosts
35
hosts = zapi.host.get(monitored_hosts=1, output='extend')
36

37
# Get disabled hosts using raw request
38
disabled_hosts = zapi.do_request('host.get', {
39
    'filter': {'status': 1},
40
    'output': 'extend'
41
})
42

43
# Logout when done
44
zapi.user.logout()
45
```
46

47
### Metric Sending
48

49
```python
50
from pyzabbix import ZabbixMetric, ZabbixSender
51

52
# Create metrics to send
53
metrics = [
54
    ZabbixMetric('hostname1', 'cpu_usage', 85.2),
55
    ZabbixMetric('hostname1', 'memory_usage', '60%'),
56
    ZabbixMetric('hostname1', 'disk_free', 1024, 1411598020),  # with timestamp
57
]
58

59
# Send metrics to Zabbix server
60
sender = ZabbixSender(zabbix_server='192.168.1.100')
61
result = sender.send(metrics)
62
```
63

64
## Architecture
65

66
py-zabbix provides two main functional areas:
67

68
- **API Interface**: ZabbixAPI class provides a Python interface to Zabbix's JSON-RPC API with automatic authentication, session management, and dynamic method dispatch
69
- **Metric Sender**: ZabbixSender enables pushing monitoring data to Zabbix trappers with batch processing and configurable connection parameters
70

71
The library supports Python 2 and 3, includes automatic password masking for security, context manager support for resource cleanup, and built-in logging capabilities.
72

73
## Capabilities
74

75
### Zabbix API Interface
76

77
Complete interface to Zabbix's JSON-RPC API with authentication management, dynamic method dispatch, and comprehensive error handling for all Zabbix monitoring operations.
78

79
```python { .api }
80
class ZabbixAPI:
81
    def __init__(self, url=None, use_authenticate=False, use_basic_auth=False, user=None, password=None): ...
82
    def api_version(self): ...
83
    def do_request(self, method, params=None): ...
84
    def get_id(self, item_type, item=None, with_id=False, hostid=None, **args): ...
85
```
86

87
[Zabbix API Interface](./api-interface.md)
88

89
### Metric Sending
90

91
Send monitoring metrics to Zabbix server via trapper protocol with batch processing, configurable connection parameters, and comprehensive response handling.
92

93
```python { .api }
94
class ZabbixSender:
95
    def __init__(self, zabbix_server='127.0.0.1', zabbix_port=10051, use_config=None, chunk_size=250, socket_wrapper=None, timeout=10): ...
96
    def send(self, metrics): ...
97

98
class ZabbixMetric:
99
    def __init__(self, host, key, value, clock=None): ...
100

101
class ZabbixResponse:
102
    def parse(self, response): ...
103
```
104

105
[Metric Sending](./metric-sending.md)
106

107
## Exception Handling
108

109
```python { .api }
110
class ZabbixAPIException(Exception):
111
    """Custom exception for Zabbix API errors"""
112
    def __init__(self, error): ...
113
```
114

115
The ZabbixAPIException provides detailed error information including error code, message, and sanitized request data for debugging.