7 Ficheros XML de consultas: parte común

7.1 Qué es común y qué depende del motor#

Un fichero XML de consultas tiene siempre la misma estructura: un elemento raíz <Queries> con declaraciones globales y una lista de consultas. Cada consulta combina elementos comunes con elementos propios del motor:

<Queries engine="...">                        <!-- común -->

    <environment name="..." default="..."/>   <!-- común -->
    <script language="...">...</script>       <!-- común -->
    <context .../>                            <!-- solo Database -->
    <authentication ...>...</authentication>  <!-- solo Webservice -->

    <query name="..." module="..." ...>       <!-- común + atributos del motor -->
        <sql>...</sql>                        <!-- solo Database -->
        <url>...</url>                        <!-- solo Webservice -->
        <parameter order="..." .../>          <!-- común + atributos del motor -->
        <item name="..." .../>                <!-- común + atributos del motor -->
        <field name="..." .../>               <!-- común + atributos del motor -->
        <script>...</script>                  <!-- común -->
    </query>

</Queries>

La tabla 7.1 resume qué elementos y atributos existen en cada motor.

Tabla 7.1. Elementos y atributos por motor

7.2 Reglas generales#

• Los nombres de elementos y atributos no distinguen mayúsculas de minúsculas (<Queries> y <queries> son equivalentes).

• Un atributo o elemento desconocido, o que no corresponde al motor, es un error: el monitor no arranca y el error aparece en su log.

• Conviene escribir el texto de las consultas y los scripts dentro de una sección <![CDATA[ ... ]]> para no tener que escapar <, > ni &.

• Si un monitor carga varios ficheros (varias líneas QueryFile), todos deben ser del mismo motor. Los nombres de consulta y de ítem deben ser únicos en el conjunto de ficheros.

7.3 El elemento <Queries>#

Es el elemento raíz y admite estos atributos:

Si la versión instalada es menor que la exigida, el monitor no arranca y lo indica en el log.

7.4 Variables de entorno: <environment>#

Las variables de entorno permiten parametrizar un XML para reutilizarlo en varias instalaciones: nombres de esquema, bases de datos, contextos…

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

Se usan con la sintaxis ${Nombre}. Dónde se sustituyen depende del motor: en Database, en el texto SQL, en los atributos de contextos, <default> y <parameter>, y en las condiciones de <when> con environment(’Nombre’); en Webservice, en el texto de los elementos <header> de las autenticaciones HTTPAuth.

<sql><![CDATA[
    select count(*) as n from ${SvmSchema}.f986110
    ]]>
</sql>

El valor de una variable se toma de la primera de estas fuentes que la defina:

1. Environment en el fichero .conf del monitor.

2. Environment en databbix.conf.

3. El atributo default del <environment> en el XML.

Por ejemplo, para que un monitor use el esquema svm910:

[General]
Environment = SvmSchema=svm910

Una variable sin definir se sustituye por una cadena vacía.

7.5 Scripts: <script>#

Un <script> contiene funciones en JavaScript o Python que se usan para transformar valores o respuestas. Se puede poner en el nivel de <Queries>, y entonces está disponible en todas las consultas, o dentro de un <query>, y entonces solo está disponible en esa consulta.

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

Todos los scripts de una colección de consultas deben usar el mismo lenguaje. El capítulo 12 explica cómo programarlos.

7.6 La consulta: <query>#

7.7 El elemento <item>#

Cada <item> declara un ítem de Zabbix que produce la consulta. Estos son sus atributos comunes; cada motor añade los atributos que indican de dónde sale el valor (column en Database, path y type en Webservice).

Un mismo dato puede alimentar varios ítems con nombres distintos, por ejemplo para mantener una clave antigua y una nueva a la vez:

<item name="tez.ora.queryversion" column="version"/>
<item name="ts.db.queryversion"   column="version"/>

7.8 El elemento <parameter>#

Relaciona cada parámetro de la clave de Zabbix con la consulta. Estos son los atributos comunes; el atributo que dice para qué se usa el parámetro depende del motor (column, bind o context en Database; path o urlparameter en Webservice).

Los parámetros de la clave se separan solo por comas y se eliminan los espacios de los extremos. No se interpretan comillas, así que un parámetro no puede contener comas.

7.9 Consultas de descubrimiento#

En todos los motores, una consulta con discovery="yes" produce el JSON de una regla de descubrimiento de bajo nivel de Zabbix:

{"data":[ {"{#MACRO1}":"valor", "{#MACRO2}":"valor"}, ... ]}

• Cada entidad descubierta (una fila, un elemento de un array JSON, un topic) es un elemento de data.

• Cada <field> define una macro: el atributo name es el nombre de la macro sin {# ni }, y el atributo propio del motor indica de dónde sale su valor.

• Los <item> de un descubrimiento solo llevan name y, opcionalmente, transform; en ese caso la función recibe el JSON completo (sección 12.5).

7.10 Consultas constantes#

Con type="Constant", la consulta no accede a la fuente de datos: cada <item> devuelve el valor de su atributo value. Funcionan con cualquier motor y se suelen usar para publicar la versión del fichero de consultas:

<query name="JDEVersion" module="JDE" type="Constant">
    <item name="ts.jde.queryversion" value="$Id: manual-databbix.tex 2699 2026-10-28 12:19:58Z bruno $"/>
</query>