Quickstart guide

After you have installed zabbix_utils, you can use it in your script.

This quickstart guide shows you how to:

• Retrieve the hostname from Zabbix agent.
• Create a host and a trapper item using Zabbix API.
• Send a value to the item.

The guide presents the script step by step, explaining each part as it is introduced. The complete script is provided at the end of the page.

The guide also assumes your Zabbix server, agent, and API are running locally.

Retrieve hostname from Zabbix agent

Start by retrieving the hostname of the system where Zabbix agent is running. You will need this hostname to create a host using Zabbix API.

1. Import the Getter class from zabbix_utils. This class works like Zabbix get and lets you request data from Zabbix agent.

2. Create a Getter instance that connects to the local Zabbix agent at 127.0.0.1 on port 10050.

3. Call the get() method on the Getter instance to request the hostname from Zabbix agent.

• The get() method takes an item key as its parameter and sends a request to Zabbix agent for that item.
• The get() method returns an object, and the hostname is stored inside the value attribute of that object.
• system.hostname is a built-in Zabbix agent key that returns the host's name.

from zabbix_utils import Getter
       
       agent = Getter(host='127.0.0.1', port=10050)
       hostname = agent.get('system.hostname').value

Connect and log in to Zabbix API

Next, connect to the Zabbix API. This lets your script manage Zabbix objects such as hosts and items.

1. Import the ZabbixAPI class from zabbix_utils.

2. Create a ZabbixAPI instance and provide the URL of your Zabbix web interface.

3. Call the login() method on the ZabbixAPI instance and provide your username and password. The account must have permission to access Zabbix API.

4. Call the logout() method to close the session after API operations.

from zabbix_utils import ZabbixAPI
       
       api = ZabbixAPI(url='127.0.0.1/zabbix')
       api.login(user='Admin', password='zabbix')
       
       # API operations go here
       
       api.logout()

Create host in Zabbix

Now that you have the hostname from Zabbix agent and you're connected to Zabbix API, you can create a new host in Zabbix.

1. Call the host.create() API method on the ZabbixAPI instance and provide the host details:

• host - set to the hostname variable containing the hostname you retrieved from Zabbix agent.
• interfaces - contains connection details for Zabbix agent that's running on the host.
• groups - contains at least one host group the host should belong to.

2. Since Zabbix API returns the ID of the newly created host, save this ID in the host_id variable for later use.

3. Print a message to confirm the host was created.

api.host.create(
           host=hostname,
           interfaces=[{
               'type': 1,
               'main': 1,
               'useip': 1,
               'ip': '127.0.0.1',
               'dns': '',
               'port': '10050',
           }],
           groups=[{'groupid': '2'}]
       )
       
       host_id = host['hostids'][0]
       
       print(f"Host '{hostname}' created with ID {host_id}")

Create new item in Zabbix

After creating a host, you can add an item to it.

1. Define a unique key for the item to be created.

2. Call the item.create() method on the ZabbixAPI instance and provide the item details:

• hostid - set to the host_id variable containing the ID of the host you just created.
• name - a name for the item.
• key_ - set to the item_key variable you just defined.
• type - set to 2 (trapper item), required to receive values sent from your script in the following steps.
• value_type - set to 3 (numeric unsigned), the type of data this item stores.

3. Since Zabbix API returns the ID of the newly created item, save this ID in the item_id variable for later use.

4. Print a message to confirm the item was created.

item_key = 'app.myservice.heartbeat'
       
       item = api.item.create(
           hostid=host_id,
           name='App heartbeat',
           key_=item_key,
           type=2,
           value_type=3,
       )
       
       item_id = item['itemids'][0]
       
       print(f"Item '{item_key}' created with ID {item_id}")

Send value to host

Now that you've created your host and item, you can send data to it.

1. Import the time class and wait a few seconds before sending the data. This ensures Zabbix has fully processed your new host and item.

2. Import the Sender class from zabbix_utils. This class works like Zabbix sender and lets your script send data to Zabbix.

3. Create a Sender instance that connects to the local Zabbix server at 127.0.0.1 on port 10051.

4. Call the send_value() method on the Sender instance to send a value to your host's item and provide these details:

• hostname - set to the hostname variable containing the hostname you retrieved from Zabbix agent.
• item_key - set to the item_key variable you just defined earlier in your script.
• 1 - the value to send.

4. Print a message to confirm the value was sent.

import time
       time.sleep(10)
       
       from zabbix_utils import Sender
       
       sender = Sender(server='127.0.0.1', port=10051)
       
       response = sender.send_value(hostname, item_key, 1)
       
       print(f"Sender response: {response}")

After this code runs successfully, you should see a success message indicating Zabbix received your value:

Sender response: {"processed": 1, "failed": 0, "total": 1, "time": "0.000151", "chunk": 1}

Now you can also check your Zabbix web interface (Monitoring > Latest data) to see the value.

Complete script

Below is the complete script that combines all the steps: retrieving the hostname, creating the host and item using Zabbix API, and sending data to Zabbix.

import time
       from zabbix_utils import Getter, ZabbixAPI, Sender
       
       # Retrieve host name from Zabbix agent
       agent = Getter(host='127.0.0.1', port=10050)
       hostname = agent.get('system.hostname').value
       
       # Connect and log in to Zabbix API
       api = ZabbixAPI(url='127.0.0.1/zabbix')
       api.login(user='Admin', password='zabbix')
       
       # Create host in Zabbix
       host = api.host.create(
           host=hostname,
           interfaces=[{
               'type': 1,
               'main': 1,
               'useip': 1,
               'ip': '127.0.0.1',
               'dns': '',
               'port': '10050',
           }],
           groups=[{'groupid': '2'}]
       )
       
       host_id = host['hostids'][0]
       
       print(f"Host '{hostname}' created with ID {host_id}")
       
       # Create item in Zabbix
       item_key = 'app.myservice.heartbeat'
       
       item = api.item.create(
           hostid=host_id,
           name='App heartbeat',
           key_=item_key,
           type=2,
           value_type=3
       )
       
       item_id = item['itemids'][0]
       
       print(f"Item '{item_key}' created with ID {item_id}")
       
       # Log out from API
       api.logout()
       
       # Wait for Zabbix to process new host
       time.sleep(10)
       
       # Send value to host
       sender = Sender(server='127.0.0.1', port=10051)
       response = sender.send_value(hostname, item_key, 1)
       
       print(f"Sender response: {response}")