Guía de inicio rápido

Después de haber instalado zabbix_utils, puedes usarlo en tu script.

Esta guía de inicio rápido te muestra cómo:

  • Recuperar el nombre del host desde el agent de Zabbix.
  • Crear un host y un item trapper usando la API de Zabbix.
  • Enviar un valor al item.

La guía presenta el script paso a paso, explicando cada parte a medida que se introduce. El script completo se proporciona al final de la página.

La guía también asume que tu server, agent y API de Zabbix se están ejecutando localmente.

Recuperar el nombre del host desde el agente de Zabbix

Comience recuperando el nombre del host del sistema donde se está ejecutando el agente de Zabbix. Necesitará este nombre de host para crear un host usando la API de Zabbix.

1. Importe la clase Getter de zabbix_utils. Esta clase funciona como Zabbix get y le permite solicitar datos al agente de Zabbix.

2. Cree una instancia de Getter que se conecte al agente de Zabbix local en 127.0.0.1 en el puerto 10050.

3. Llame al método get() en la instancia de Getter para solicitar el nombre del host al agente de Zabbix.

  • El método get() toma una clave de item como parámetro y envía una solicitud al agente de Zabbix para ese item.
  • El método get() devuelve un objeto, y el nombre del host se almacena dentro del atributo value de ese objeto.
  • system.hostname es una clave incorporada del agente de Zabbix que devuelve el nombre del host.
from zabbix_utils import Getter

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

Conectar e iniciar sesión en la API de Zabbix

A continuación, conéctese a la API de Zabbix. Esto permite que su script gestione objetos de Zabbix como hosts e items.

1. Importe la clase ZabbixAPI de zabbix_utils.

2. Cree una instancia de ZabbixAPI y proporcione la URL de su interfaz web de Zabbix.

3. Llame al método login() en la instancia de ZabbixAPI y proporcione su nombre de usuario y contraseña. La cuenta debe tener permiso para acceder a la API de Zabbix.

4. Llame al método logout() para cerrar la sesión después de las operaciones de la API.

from zabbix_utils import ZabbixAPI

api = ZabbixAPI(url='127.0.0.1/zabbix')
api.login(user='Admin', password='zabbix')

# Las operaciones de la API van aquí

api.logout()

Crear un host en Zabbix

Ahora que tienes el nombre de host del agent de Zabbix y estás conectado a la API de Zabbix, puedes crear un nuevo host en Zabbix.

1. Llama al método de la API host.create() en la instancia de ZabbixAPI y proporciona los detalles del host:

  • host - establece la variable hostname que contiene el nombre de host que recuperaste del agent de Zabbix.
  • interfaces - contiene los detalles de conexión para el agent de Zabbix que se está ejecutando en el host.
  • groups - contiene al menos un grupo de hosts al que debe pertenecer el host.

2. Dado que la API de Zabbix devuelve el ID del host recién creado, guarda este ID en la variable host_id para su uso posterior.

3. Imprime un mensaje para confirmar que el host fue creado.

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}' creado con ID {host_id}")

Crear un nuevo item en Zabbix

Después de crear un host, puede añadirle un item.

1. Defina una clave única para el item que va a crear.

2. Llame al método item.create() en la instancia de ZabbixAPI y proporcione los detalles del item:

  • hostid - establezca el valor de la variable host_id que contiene el ID del host que acaba de crear.
  • name - un nombre para el item.
  • key_ - establezca el valor de la variable item_key que acaba de definir.
  • type - establezca el valor 2 (item trapper), necesario para recibir los valores enviados desde su script en los siguientes pasos.
  • value_type - establezca el valor 3 (numérico sin signo), el tipo de dato que almacenará este item.

3. Dado que la API de Zabbix devuelve el ID del item recién creado, guarde este ID en la variable item_id para su uso posterior.

4. Imprima un mensaje para confirmar que el item se ha creado.

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}' creado con ID {item_id}")

Enviar valor al host

Ahora que ha creado su host y su item, puede enviarle datos.

1. Importe la clase time y espere unos segundos antes de enviar los datos. Esto asegura que Zabbix haya procesado completamente su nuevo host y su item.

2. Importe la clase Sender de zabbix_utils. Esta clase funciona como Zabbix sender y permite que su script envíe datos a Zabbix.

3. Cree una instancia de Sender que se conecte al servidor Zabbix local en 127.0.0.1 en el puerto 10051.

4. Llame al método send_value() en la instancia de Sender para enviar un valor al item de su host y proporcione estos detalles:

  • hostname - establezca el valor de la variable hostname que contiene el nombre del host que recuperó del agent de Zabbix.
  • item_key - establezca el valor de la variable item_key que acaba de definir anteriormente en su script.
  • 1 - el valor a enviar.

4. Imprima un mensaje para confirmar que se envió el valor.

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}")

Después de que este código se ejecute correctamente, debería ver un mensaje de éxito que indica que Zabbix recibió su valor:

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

Ahora también puede comprobar la interfaz web de Zabbix (Supervisión > Últimos datos) para ver el valor.

Script completo

A continuación se muestra el script completo que combina todos los pasos: recuperar el nombre del host, crear el host y el item usando la API de Zabbix y enviar datos a Zabbix.

import time
from zabbix_utils import Getter, ZabbixAPI, Sender

# Recuperar el nombre del host desde el agent de Zabbix
agent = Getter(host='127.0.0.1', port=10050)
hostname = agent.get('system.hostname').value

# Conectar e iniciar sesión en la API de Zabbix
api = ZabbixAPI(url='127.0.0.1/zabbix')
api.login(user='Admin', password='zabbix')

# Crear el host en 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}' creado con ID {host_id}")

# Crear el item en 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}' creado con ID {item_id}")

# Cerrar sesión en la API
api.logout()

# Esperar a que Zabbix procese el nuevo host
time.sleep(10)

# Enviar valor al host
sender = Sender(server='127.0.0.1', port=10051)
response = sender.send_value(hostname, item_key, 1)

print(f"Respuesta del sender: {response}")