13 The queryexplorer utility

queryexplorer is an interactive tool to test a monitor’s configuration without starting the daemon and without sending anything to Zabbix. It loads the same .conf file and the same XML files the monitor would use, connects to the data source and lets you run items one by one and see the result. It is used to:

check that a monitor file and its XML files are correct;
check that the connection to the database or service works (and, for web services, that authentication is correct);
test a new query and its transformations before creating the items in Zabbix;
inspect contexts, environment variables and runtime data, and evaluate <when> conditions.

It is installed in /opt/trustserver/bin/queryexplorer.

13.1 Invocation#

queryexplorer [options] -f <monitor.conf> [command [arguments] ...]

Option	Description
`-f, --conf-config-file` `f`	Mandatory. Monitor file to test. If the path does not start with `/`, it is looked up in the monitor directory (`/etc/databbix/dbs`).
`-l, --log-console`	Also shows the log on the console. Highly recommended: without it, loading errors only go to the log file.
`-v, --logLevel` `n`	Log level (overrides the one in `databbix.conf`). With 9, SQL statements, HTTP calls and their responses are shown.
`-c, --config-file` `f`	Global configuration file. Default: `/etc/databbix/databbix.conf`.
`-p, --config-path` `d`	Monitor directory, to resolve relative paths in `-f`.
`-m, --module-path` `d`	Additional module directories.
`-h, --help`	Shows help.

On startup, queryexplorer does the same as a monitor:

reads databbix.conf and the file given with -f;
loads the XML query files;
connects to the data source.

If any of these steps fails, it shows the error and exits. Therefore, starting without errors already validates the configuration and the connection.

Note. queryexplorer writes its log to the global log file (LogPath/LogFile in databbix.conf). Run it as the databbix user (or another user with write permission on that file) and with the same environment variables as the service.

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 opens its own connection, so it can be used while the service is running.

13.2 Interactive mode#

With no commands on the command line, queryexplorer enters interactive mode:

$ 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[sales]
Item: tez.pg.sessions[sales], value: 12
QueryExplorer> quit

Quitting Databbix.  See you soon!

The Tab key completes command names and, depending on the command, item, query, context or variable names.
The arrow keys browse the history, which is saved in ~/.queryexplorer_history.
Exit with quit or Ctrl-D.
Commands are case-insensitive. Arguments are separated by spaces, so an item key cannot contain spaces.

13.3 Non-interactive mode#

If commands are given after the options, they are run in order and the program exits. Each command takes its arguments from the words that follow it:

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

Quote keys with brackets so that the shell does not interpret them. This mode is useful in check scripts after an installation or upgrade.

13.4 Commands#

13.4.1 Items and queries#

Command	Description
`get` `key`	Runs the item’s query and shows its value, exactly as the monitor would compute it: with the key’s parameters and context and applying transformations. It ignores the cache: the query is always run.
`listItems`	Lists the names of all the items in the collection.
`listItems full`	Lists all queries with their text (SQL or URL) and, for each item, its parameters and the column or path it comes from.
`listQueries`	Lists the query names.
`descQuery` `name`	Shows a query (by its name or by one of its items’ names): text and list of items.
`descItem` `item`	Shows the query an item belongs to and where its value comes from.

13.4.2 Contexts#

Command	Description
`getDefinedContexts`	Contexts declared in the XML files, with their default value.
`getSupportedContexts`	Contexts supported by the connection, with their current value.
`getContext` `name`	Current value of a context in the connection.
`setContext` `name value`	Changes a context of the connection. Useful to check that it can be entered (for example, a particular database).
`setContext` `name`	Resets the context to its default value.
`setContext`	Resets all contexts to their default values.

The get command switches to the context given by the key and, when done, leaves the connection in the context it was in.

13.4.3 Variables and expressions#

Command	Description
`getEnvironment` `name`	Value of an environment variable, as the monitor sees it (combining the XML file, `databbix.conf` and the `.conf`).
`getRuntimeNames`	Names of the runtime data offered by the connection.
`getRuntimeValue` `name`	Value of a runtime datum.
`evaluateExpression` `expression`	Evaluates an expression like `<when>` conditions. Shows `1` if it holds and `0` otherwise.

Note. In queryexplorer, runtime(’DATABBIX.PROGRAM_NAME’) returns queryexplorer instead of databbix. A condition can use it to behave differently during testing.

Warning. In interactive mode, evaluateExpression takes the whole rest of the line as the expression. In non-interactive mode it takes a single argument, so the expression must be quoted for the shell to pass it as one parameter:

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

13.4.4 Other#

Command	Description
`help`	List of commands.
`quit`	Leaves interactive mode.

13.5 Use cases#

13.5.1 Validating a monitor file and its connection#

queryexplorer -l -f oraprod.conf listQueries

If the command lists the queries, the .conf is correct, the XML files loaded without errors and the connection works. Otherwise, the console log says what failed: a missing mandatory parameter, a syntax error in an XML file (with the query name) or the driver’s connection error.

13.5.2 Validating web service authentication#

In a Webservice monitor, authentication happens on the first call. Requesting an item with a detailed log is enough to see the login request, the response and the result of the authentication functions:

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

13.5.3 Testing a new query#

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

The second get checks that the default attribute works when the row does not exist. If a value is not as expected, repeat with -v 9 to see the statement run, the rows obtained and the calls to the transformation functions.

13.5.4 Checking alternative SQL#

To find out which branch of a <multiple> will be used with a database:

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

13.5.5 Checking contexts#

To verify that the user can enter all the databases of an SQL Server before enabling a discovery across contexts:

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