13 La utilidad queryexplorer

queryexplorer es una herramienta interactiva para probar la configuración de un monitor sin arrancar el demonio y sin enviar nada a Zabbix. Carga el mismo fichero .conf y los mismos XML que usaría el monitor, se conecta a la fuente de datos y permite ejecutar ítems uno a uno y ver el resultado. Sirve para:

comprobar que un fichero de monitor y sus XML son correctos;
comprobar que la conexión con la base de datos o el servicio funciona (y, en webservices, que la autenticación es correcta);
probar una consulta nueva y sus transformaciones antes de crear los ítems en Zabbix;
ver los contextos, variables de entorno y datos de ejecución, y evaluar las condiciones de <when>.

Se instala en /opt/trustserver/bin/queryexplorer.

13.1 Invocación#

queryexplorer [opciones] -f <monitor.conf> [comando [argumentos] ...]

Opción	Descripción
`-f, --conf-config-file` `f`	Obligatoria. Fichero de monitor que se prueba. Si la ruta no empieza por `/`, se busca en el directorio de monitores (`/etc/databbix/dbs`).
`-l, --log-console`	Muestra el log también en la consola. Muy recomendable: sin ella, los errores de carga solo quedan en el fichero de log.
`-v, --logLevel` `n`	Nivel de log (sustituye al de `databbix.conf`). Con 9 se ven las sentencias SQL, las llamadas HTTP y sus respuestas.
`-c, --config-file` `f`	Fichero de configuración global. Por defecto, `/etc/databbix/databbix.conf`.
`-p, --config-path` `d`	Directorio de monitores, para resolver rutas relativas en `-f`.
`-m, --module-path` `d`	Directorios adicionales de módulos.
`-h, --help`	Muestra la ayuda.

Al arrancar, queryexplorer hace lo mismo que un monitor:

lee databbix.conf y el fichero indicado con -f;
carga los XML de consultas;
se conecta a la fuente de datos.

Si cualquiera de estos pasos falla, muestra el error y termina. Por tanto, arrancar sin errores ya valida la configuración y la conexión.

Nota. queryexplorer escribe su log en el fichero de log global (LogPath/LogFile de databbix.conf). Ejecútelo con el usuario databbix (o con otro que tenga permiso de escritura en ese fichero) y con las mismas variables de entorno que el servicio.

sudo -u databbix env TNS_ADMIN=/etc/databbix ODBCINI=/etc/databbix/odbc.ini \
     LD_LIBRARY_PATH=/opt/trustserver/lib64 \
     /opt/trustserver/bin/queryexplorer -l -f oraprod.conf

queryexplorer abre su propia conexión, así que se puede usar con el servicio en marcha.

13.2 Modo interactivo#

Sin comandos en la línea de órdenes, queryexplorer entra en modo interactivo:

$ queryexplorer -l -f pgprod.conf

Databbix QueryExplorer: Interactive Query Tool Version 2.5.0-2639.
Databbix Database Engine Version 2.5.0-2639.
(C) Trustserver SL 2014-2024.  All Rights Reserved.

QueryExplorer> get tez.pg.sessions[ventas]
Item: tez.pg.sessions[ventas], value: 12
QueryExplorer> quit

Quitting Databbix.  See you soon!

La tecla Tab completa los nombres de comando y, según el comando, los nombres de ítem, de consulta, de contexto o de variable.
Las flechas recorren el historial, que se guarda en ~/.queryexplorer_history.
Se sale con quit o con Ctrl-D.
Los comandos no distinguen mayúsculas de minúsculas. Los argumentos se separan por espacios, así que una clave de ítem no puede contener espacios.

13.3 Modo no interactivo#

Si se ponen comandos después de las opciones, se ejecutan en orden y el programa termina. Cada comando toma sus argumentos de los que le siguen:

queryexplorer -l -f pgprod.conf \
    get 'tez.pg.sessions[ventas]' \
    get 'tez.pg.sessions[postgres]' \
    get tez.pg.db.discovery

Conviene poner las claves con corchetes entre comillas para que la shell no los interprete. Este modo es útil en scripts de comprobación tras una instalación o actualización.

13.4 Comandos#

13.4.1 Ítems y consultas#

Comando	Descripción
`get` `clave`	Ejecuta la consulta del ítem y muestra su valor, igual que lo calcularía el monitor: con los parámetros y el contexto de la clave y aplicando las transformaciones. Ignora la caché: siempre ejecuta la consulta.
`listItems`	Lista los nombres de todos los ítems de la colección.
`listItems full`	Lista todas las consultas con su texto (SQL o URL) y, para cada ítem, sus parámetros y la columna o ruta de la que sale.
`listQueries`	Lista los nombres de las consultas.
`descQuery` `nombre`	Muestra una consulta (por su nombre o por el de uno de sus ítems): texto y relación de ítems.
`descItem` `ítem`	Muestra la consulta a la que pertenece un ítem y de dónde sale su valor.

13.4.2 Contextos#

Comando	Descripción
`getDefinedContexts`	Contextos declarados en los XML, con su valor por defecto.
`getSupportedContexts`	Contextos que admite la conexión, con su valor actual.
`getContext` `nombre`	Valor actual de un contexto en la conexión.
`setContext` `nombre valor`	Cambia un contexto de la conexión. Sirve para comprobar que se puede entrar en él (por ejemplo, en una base de datos concreta).
`setContext` `nombre`	Vuelve a poner el contexto en su valor por defecto.
`setContext`	Vuelve a poner todos los contextos en su valor por defecto.

El comando get cambia al contexto que indica la clave y, al terminar, deja la conexión en el contexto en que estaba.

13.4.3 Variables y expresiones#

Comando	Descripción
`getEnvironment` `nombre`	Valor de una variable de entorno, tal como la ve el monitor (combinando XML, `databbix.conf` y `.conf`).
`getRuntimeNames`	Nombres de los datos de ejecución que ofrece la conexión.
`getRuntimeValue` `nombre`	Valor de un dato de ejecución.
`evaluateExpression` `expresión`	Evalúa una expresión como las condiciones de `<when>`. Muestra `1` si se cumple y `0` si no.

Nota. En queryexplorer, runtime(’DATABBIX.PROGRAM_NAME’) devuelve queryexplorer en lugar de databbix. Una condición puede usarlo para comportarse de forma distinta durante las pruebas.

Atención. En modo interactivo, evaluateExpression toma como expresión todo el resto de la línea. En modo no interactivo toma un único argumento, así que la expresión debe ir entre comillas para que la shell la pase como un solo parámetro:

queryexplorer -l -f oraprod.conf \
    evaluateExpression "runtime('DB.DATABASE') = 'Oracle'"

13.4.4 Otros#

Comando	Descripción
`help`	Lista de comandos.
`quit`	Sale del modo interactivo.

13.5 Casos de uso#

13.5.1 Validar un fichero de monitor y su conexión#

queryexplorer -l -f oraprod.conf listQueries

Si el comando lista las consultas, el .conf es correcto, los XML se han cargado sin errores y la conexión funciona. Si no, el log en consola indica qué ha fallado: un parámetro obligatorio que falta, un error de sintaxis en un XML (con el nombre de la consulta) o el error de conexión del driver.

13.5.2 Validar la autenticación de un webservice#

En un monitor Webservice, la autenticación se produce en la primera llamada. Basta con pedir un ítem con el log detallado para ver la petición de login, la respuesta y el resultado de las funciones de autenticación:

queryexplorer -l -v 9 -f aisprod.conf get ts.ais.scheduler.state

13.5.3 Probar una consulta nueva#

QueryExplorer> descQuery LocalInvalidObjects
QueryExplorer> get local.ora.invalid[HR]
Item: local.ora.invalid[HR], value: 3
QueryExplorer> get local.ora.invalid[NOEXISTE]
Item: local.ora.invalid[NOEXISTE], value: 0
QueryExplorer> get local.ora.schema.discovery
Item: local.ora.schema.discovery, value: {"data":[{"{#SCHEMA}":"HR"}, ...]}

El segundo get comprueba que el atributo default funciona cuando la fila no existe. Si un valor no es el esperado, repita con -v 9 para ver la sentencia ejecutada, las filas obtenidas y las llamadas a las funciones de transformación.

13.5.4 Comprobar el SQL alternativo#

Para saber qué rama de un <multiple> se usará con una base de datos:

QueryExplorer> getRuntimeValue DB.DATABASE
DB.DATABASE = 'Oracle'
QueryExplorer> evaluateExpression runtime('DB.DATABASE') = 'Oracle'
Result: 1

13.5.5 Comprobar los contextos#

Para verificar que el usuario puede entrar en todas las bases de datos de un SQL Server antes de activar un descubrimiento por contextos:

QueryExplorer> getDefinedContexts
Contexts defined in query file:
  - DATABASE, default: master
QueryExplorer> setContext Database ventas
QueryExplorer> getContext Database
Actual value for context 'Database': 'ventas'
QueryExplorer> setContext