3 Conceptos

3.1 Host, ítem y clave#

Son conceptos de Zabbix:

Host.

Elemento monitorizado en Zabbix. Cada monitor de Databbix envía los datos de un único host, identificado por General.Name.

Ítem.

Dato que Zabbix recoge periódicamente de un host (número de sesiones, espacio libre de un tablespace…). Los ítems que atiende Databbix son de tipo Zabbix agent (active).

Clave.

Identificador del ítem, con la forma nombre[parámetro1,parámetro2,...]. El nombre indica qué ítem de qué consulta hay que calcular y los parámetros indican sobre qué objeto (qué tablespace, qué base de datos…).

Ejemplo. El host ORAPROD de Zabbix tiene un ítem activo con la clave:

tez.ora.tspace.pctfree[USERS]

El monitor cuyo .conf tiene Name = ORAPROD busca en sus XML el <item> llamado tez.ora.tspace.pctfree y lo calcula para el tablespace USERS.

3.2 Monitor#

Un monitor es la unidad de trabajo de Databbix: une una fuente de datos con un host de Zabbix. Se define en un fichero .conf y se ejecuta en su propio hilo. Por ejemplo, si una máquina vigila tres bases de datos, hay tres ficheros .conf, tres monitores y tres hosts en Zabbix.

Un monitor está formado por:

• un motor y una conexión con la fuente de datos;

• una colección de consultas;

• una conexión con el servidor Zabbix y la lista de ítems activos del host;

• un planificador que decide cuándo ejecutar cada consulta.

Ejemplo. Fichero /etc/databbix/dbs/oraprod.conf con lo mínimo para un monitor de Oracle:

[General]
Name = ORAPROD                 # host en Zabbix

[Zabbix]
Server = zabbix.empresa.com    # a quién se envían los datos
Port = 10051

[Data]
Module = DB                    # módulos de consultas que usa

[Database]                     # de dónde se sacan los datos
DBDriver = Oracle
ConnectionString = oraprod
UserName = zabbix
Password = secreto

3.3 Motor de consultas#

El motor (engine) es el componente que sabe hablar con un tipo de fuente de datos. Cada monitor usa un único motor, que se elige con General.Engine. El motor determina:

• qué sección de conexión lleva el fichero de monitor ([Database], [Webservice] o [MQTT]);

• qué elementos y atributos admiten los XML (por ejemplo, <sql> en Database y <url> en Webservice);

• qué tipos de consulta existen y cómo se obtienen los valores.

Todos los ficheros XML de un monitor deben ser del motor del monitor: el motor se declara en el atributo engine de <Queries>.

Ejemplo. Un monitor de servicio REST declara el motor en su .conf:

[General]
Name = JDEPROD
Engine = Webservice
QueryFile = /etc/databbix/query-jde.xml

[Webservice]
BaseURL = https://jde.empresa.com:9888/restservice

y el XML que usa declara el mismo motor:

<Queries engine="Webservice">
    ...
</Queries>

3.4 Colección de consultas#

Es el conjunto de consultas que resulta de cargar los ficheros XML de un monitor (QueryFile). Dentro de una colección, los nombres de consulta y de ítem son únicos: así, Databbix sabe qué consulta ejecutar para cada clave que le pide Zabbix.

Si varios monitores usan el mismo motor, los mismos ficheros y las mismas variables de entorno, comparten una única copia de la colección en memoria.

Ejemplo. Colección formada por el fichero de consultas de la distribución y uno propio:

[General]
QueryFile = /etc/databbix/query.xml
QueryFile = /etc/databbix/query-local.xml

3.5 Consulta#

Una consulta (<query>) define una operación sobre la fuente de datos (una sentencia SQL, una llamada a un servicio…) y los ítems de Zabbix que se obtienen de su resultado. Una consulta puede producir muchos ítems, y Databbix la ejecuta una sola vez para todos ellos.

Según cómo se relaciona el resultado con los ítems, hay varios tipos: básica, filtro, bind, descubrimiento y constante. Se describen en el capítulo 7.

Ejemplo. Una consulta básica que produce dos ítems a partir de una sola sentencia:

<query name="PGWriter" module="PG">
    <sql><![CDATA[
        select checkpoints_timed, checkpoints_req
        from pg_stat_bgwriter
        ]]>
    </sql>
    <item name="tez.pg.checkpointtimed" column="checkpoints_timed"/>
    <item name="tez.pg.checkpointreq"   column="checkpoints_req"/>
</query>

3.6 Ítem de consulta#

Dentro de una consulta, cada <item> indica de dónde sale el valor de un ítem de Zabbix: de qué columna del resultado SQL, de qué ruta de la respuesta JSON, de un dato interno (tiempo de ejecución)… Su atributo name es el nombre de la clave en Zabbix.

Además de los ítems definidos en los XML, Databbix responde a unos pocos ítems internos, como agent.ping o agent.version.

Ejemplo. Tres formas de obtener el valor:

<!-- de una columna SQL -->
<item name="tez.ora.sessions" column="n"/>
<!-- de una ruta dentro de la respuesta JSON de un servicio -->
<item name="ts.jde.instance.state" path="instanceState" type="INT"/>
<!-- de un dato interno: segundos que tardó la consulta -->
<item name="tez.ora.tspace.exectime" built_in="exec_time"/>

3.7 Parámetro#

Un parámetro (<parameter>) relaciona un parámetro de la clave de Zabbix con la consulta. Según el tipo de consulta, el valor del parámetro sirve para:

• elegir una fila del resultado (filtro);

• pasarlo a la sentencia SQL o a la URL (bind);

• elegir el contexto en el que se ejecuta la consulta.

Ejemplo. Con la clave tez.pg.sessions[ventas], el primer parámetro (ventas) elige la fila cuya columna datname vale ventas:

<parameter column="datname" order="1" type="STRING"/>

Con la clave tez.pg.param[max_connections], el primer parámetro se pasa a la sentencia SQL en la variable :name:

<parameter bind=":name" order="1" type="STRING"/>

3.8 Módulo#

Un módulo es un nombre que agrupa consultas relacionadas (DB, Instance, PG, MSSQL…). Cada consulta y cada contexto declaran su módulo con el atributo module, y cada monitor declara los módulos que usa con Data.Module.

Ejemplo.

<query name="Sessions" module="Instance"> ... </query>

[Data]
Module = DB
Module = Instance

3.9 Descubrimiento#

El descubrimiento de bajo nivel (LLD) es el mecanismo de Zabbix para crear ítems automáticamente según los objetos que existen (un ítem por tablespace, por base de datos…). En Databbix, una consulta de descubrimiento devuelve la lista de objetos en el formato JSON que espera Zabbix. Normalmente va acompañada de una consulta de filtro que calcula los valores de cada objeto descubierto.

Ejemplo. Descubrimiento de las bases de datos de un PostgreSQL:

<query name="PGDiscoverDB" module="PG" discovery="yes">
    <sql><![CDATA[
        select datname from pg_database where datname not like 'template%'
        ]]>
    </sql>
    <item name="tez.pg.db.discovery"/>
    <field name="DBNAME" column="datname"/>
</query>

El ítem tez.pg.db.discovery devuelve a Zabbix:

{"data":[{"{#DBNAME}":"postgres"},{"{#DBNAME}":"ventas"}]}

y en Zabbix se define el prototipo tez.pg.sessions[{#DBNAME}], que da lugar a tez.pg.sessions[postgres] y tez.pg.sessions[ventas].

3.10 Contexto#

Un contexto es un estado de la conexión que se puede cambiar entre consultas sin volver a conectar. Los ejemplos típicos son la base de datos activa en SQL Server o PostgreSQL y el contenedor (PDB) en Oracle multitenant. Gracias a los contextos, un único monitor con una sola conexión puede consultar todas las bases de datos de un servidor.

Los contextos solo existen en el motor Database. Se declaran en el XML con un valor por defecto. Cada consulta se ejecuta en el contexto por defecto, en uno fijo o en el que indique la clave del ítem. Databbix agrupa las consultas por contexto para cambiarlo el menor número de veces posible.

Ejemplo. Se declara el contexto Database, cuyo valor por defecto es master, y una consulta que se ejecuta en la base de datos que indique el primer parámetro de la clave:

<context name="Database" module="MSSQL" default="master"/>

<query name="MSFGSpace" module="MSSQL" select="FILTER">
    <sql> ... </sql>
    <parameter context="Database" order="1"/>
    <parameter column="filegroup_name" order="2" type="STRING"/>
    <item name="tez.mssql.fgspace.used" column="used"/>
</query>

La clave tez.mssql.fgspace.used[ventas,PRIMARY] ejecuta la consulta en la base de datos ventas y devuelve el valor del filegroup PRIMARY.

3.11 Variable de entorno#

Una variable de entorno es un valor con nombre que se sustituye en los XML con la sintaxis ${Nombre}. Sirve para escribir XML genéricos y adaptarlos a cada instalación desde la configuración: el nombre de un esquema, la base de datos de administración, etc.

No tienen relación con las variables de entorno del sistema operativo. Se definen con <environment> en el XML (valor por defecto) y con Environment = Nombre=Valor en databbix.conf o en el fichero del monitor, que tienen prioridad.

Ejemplo. El XML declara la variable y la usa en el SQL:

<environment name="SvmSchema" default="svm920"/>

<query name="JdeSpecJobs" module="JDEDB">
    <sql><![CDATA[
        select count(*) as n from ${SvmSchema}.f986110
        ]]>
    </sql>
    <item name="ts.jdedb.specjobs" column="n"/>
</query>

Un monitor que no dice nada consulta svm920.f986110. Otro monitor con esta línea consulta svm910.f986110:

[General]
Environment = SvmSchema=svm910

3.12 Datos de ejecución#

Son valores que se conocen solo una vez establecida la conexión, como el producto de base de datos al que se ha conectado el driver. Se usan en el motor Database (sección 9.2.4). Se consultan con la función runtime(’NOMBRE’) en las condiciones de <when>, para elegir el SQL adecuado a cada base de datos.

Ejemplo.

<sql>
  <multiple>
    <when condition="runtime('DB.DATABASE') = 'Oracle'"><![CDATA[
        select sysdate as ahora from dual ]]></when>
    <when><![CDATA[
        select current_timestamp as ahora ]]></when>
  </multiple>
</sql>

3.13 Scripts y transformaciones#

Los XML pueden incluir funciones escritas en JavaScript o Python (<script>). Estas funciones se usan para:

• transformar un valor antes de enviarlo a Zabbix (por ejemplo, convertir una fecha en segundos transcurridos);

• procesar la respuesta de un webservice antes de extraer los valores;

• generar credenciales y validar respuestas en las autenticaciones de webservice.

Cada monitor tiene un intérprete para su colección de consultas. Los scripts declarados en el nivel de <Queries> son comunes a todas las consultas; los declarados dentro de un <query> solo son visibles en esa consulta. Todos los scripts de una colección deben estar en el mismo lenguaje. El capítulo 12 explica cómo programarlos.

Ejemplo. Una función global y un ítem que la usa:

<script language="Javascript"><![CDATA[
    function toUnix(fecha) {
        return Math.round(Date.parse(fecha) / 1000);
    }
    ]]>
</script>

<query name="LastBackup" module="DB">
    <sql><![CDATA[
        select max(completion_time) as fin from v$backup_set ]]>
    </sql>
    <item name="local.ora.lastbackup" column="fin" transform="Javascript:toUnix"/>
</query>

3.14 Caché y planificación#

Zabbix decide cada cuánto quiere cada ítem (el intervalo de actualización del ítem). Databbix agrupa los ítems por consulta y, cuando varios ítems de la misma consulta tienen que actualizarse, ejecuta la consulta una sola vez.

El resultado de una consulta se guarda en caché durante un tiempo máximo (General.MaxCache del monitor o el atributo maxCache de la consulta, el menor de los dos). Mientras el resultado sea válido, los ítems de esa consulta se sirven desde la caché, sin volver a ejecutarla.

Ejemplo. El monitor permite reutilizar resultados durante 60 segundos, pero una consulta concreta solo durante 30:

[General]
MaxCache = 60

<query name="TSSpace" module="DB" select="FILTER" maxCache="30"> ... </query>

3.15 Autenticación de webservice#

La mayoría de los servicios web exigen autenticarse antes de responder. En Databbix intervienen tres piezas:

Motor de autenticación.

Mecanismo de autenticación programado en C++ dentro de Databbix: HTTPAuth, RESTToken, JDE y Oasis (tabla 3.1). No hay que confundirlo con el motor de consultas del monitor (Webservice).

Método de autenticación.

Personalización de un motor de autenticación para un servicio concreto, definida en un fichero de consultas con el elemento <authentication>. Tiene un nombre (atributo name), indica el motor que usa (atributo type) y aporta funciones en JavaScript o Python que deciden, por ejemplo, qué petición de login se envía, dónde está el token en la respuesta o cuándo hay que volver a autenticarse. Solo HTTPAuth y RESTToken admiten personalización.

Credenciales.

Usuario, contraseña y otros datos (entorno, rol…) que se definen en el fichero de monitor con UserName, Password y Credentials = clave=valor. Así, los XML no contienen secretos.

El parámetro Webservice.Authenticator del monitor da un nombre, que Databbix resuelve en este orden:

1. Busca en los ficheros de consultas del monitor un método de autenticación (<authentication>) con ese name. Si lo encuentra, usa su motor con las funciones del método.

2. Si no lo encuentra, busca un motor de autenticación con ese nombre y lo usa directamente, sin personalizar.

3. Si tampoco existe, el monitor no puede conectar y lo registra en su log.

Tabla 3.1. Motores de autenticación

La sesión de autenticación (por ejemplo, el token vigente) se mantiene mientras el monitor está en marcha y se renueva cuando el servicio la rechaza. Si se configura Webservice.AuthPersistFile, además se guarda en disco para reutilizarla después de un reinicio.

Ejemplo 1. Motor HTTPAuth sin personalizar: como no hay ningún método llamado HTTPAuth en los XML, se usa directamente el motor, y las credenciales van en el .conf.

[Webservice]
BaseURL = https://api.empresa.com/
Authenticator = HTTPAuth
UserName = monitor
Password = secreto
Credentials = method=BASIC

Ejemplo 2. Método de autenticación AISAuth, que personaliza el motor RESTToken, definido en el XML y usado desde el .conf:

<authentication type="RESTToken" name="AISAuth">
    <script language="Javascript"> ... </script>
    <login type="JsonPost">
        <url>v2/tokenrequest</url>
        <request-function language="Javascript" function="authGenerate"/>
        <accept-function  language="Javascript" function="authAccept"/>
    </login>
    <token type="Header" name="jde-AIS-Auth"/>
    <verify-call language="Javascript" function="verifyCall"/>
</authentication>

[Webservice]
BaseURL = https://ais.empresa.com/jderest/
Authenticator = AISAuth
UserName = monitor
Password = secreto
Credentials = environment=JPD920
Credentials = role=*ALL
AuthPersistFile = /var/lib/databbix/ais-token.json

El capítulo 12 explica cómo escribir las funciones de una autenticación.