Monex (Monitoring for eXist)

An application for monitoring, profiling and inspecting a running eXist-db instance.

Features

The app includes:

• Monitoring dashboard: live KPI strip, capacity vs workload panels — memory, page caches, embeddings status, running/waiting/recent queries
• Query profiling page: essential for tuning queries and indexes
• Index browser: inspect Lucene, range, and ngram indexes (including vector-field and vector-store when configured)
• Remote console: send log messages from any query in eXist to the remote console. Uses web sockets for real-time updates.
• Remote Monitoring: monitor multiple remote eXistdb instances. Provides timelines for long term monitoring.

Vector and embedding panels on Monitoring require eXist-db 7.x with the vector extension; they hide gracefully when unavailable.

Configure Monex

Enable Remote Monitoring

Preconditions

Monex remote monitoring requires the eXistdb scheduler module to be enabled. Make sure it is enabled in $eXistdb_home/extensions/build.properties

# Scheduler module
include.module.scheduler = true

and in $eXistdb_home/conf.xml make sure the Scheduler module is not commented out:

<module uri="http://exist-db.org/xquery/scheduler"
	class="org.exist.xquery.modules.scheduler.SchedulerModule" />

Rebuilding eXistdb

This needs only to be done if include.module.scheduler in extensions/build.properties was set to false. Then eXistdb has to be rebuild to enable the scheduler module. Shutdown the database and in the root of the eXistdb project simply call

./build.sh

After starting the database again, the remote monitoring tab should show no more error warnings.

Adding an eXistdb instance to monitor

For each eXistdb instance to monitor its url and its unique token is needed. The token can be found in the data directory on the filesystem . The file is called jmxservlet.token. The path to the data directory can be found in $existdb_home/conf.xml

<db-connection files="path-to-your-data-dir" ... />

Each eXistdb installation to monitor is added as an instance entry at /db/apps/monex/instances.xml.

Sample Monex Instances

<instance name="localhost"
	url="http://localhost:8080/exist"
    token="3268b570-392e-56ea-9550-117012413e15" cron="0 * * * * ?">
	<poll cron="0/30 * * * * ?" store="yes">
    <alert name="More than 30 threads waiting for locks to be released"
    	condition="count($jmx//LockManager/WaitingThreads/row) > 30"/>
	<alert name="More than 40 brokers active"
    	condition="$jmx//Database/ActiveBrokers &gt; 10"/>
	<alert name="Process CPU load &gt; 1.0"
    	condition="$jmx//UnixOperatingSystem/ProcessCpuLoad &gt; 0.5"/>
	</poll>
</instance>

In the Monex Remote Monitoring tab click "Run" to start all remote monitoring jobs. You should now see an entry "localhost" beneath "Remote Monitoring" and beneath that an entry "Timelines".

Building

Monex is built with Node.js + Gulp (Maven was removed in #367; the Java pieces it used to ship now live in eXist-db core ≥ 7.x).

Requirements: Git and Node.js LTS. The Node version is pinned in .nvmrc; run nvm use if you use nvm.

git clone https://github.com/eXist-db/monex.git
cd monex
npm ci
npm run build

The resulting XAR is written to dist/monex-<version>.xar. On a fresh clone, <version> is the most recently released version — the release pipeline commits it back to master (see Release procedure).

For local development against a running eXist-db, see also npm run develop (live-reload) and npm run deploy (install the built XAR into the configured eXist-db instance — set credentials in .env, see .env.example).

Release Procedure

Releases are fully automated: every push to master triggers semantic-release, which computes the next version from Conventional Commits since the last tag, builds the XAR, and publishes a GitHub Release with the XAR attached.

The pipeline takes care of:

1. Analyzing the commit history since the previous Git tag to determine the next SemVer-bumped version.
2. Writing that version into package.json so Gulp builds dist/monex-<version>.xar with the right filename.
3. Inserting a new <change version="X.Y.Z"> entry into repo.xml.tmpl based on the same commit history (via scripts/update-repo-changelog.js).
4. Committing the updated repo.xml.tmpl, package.json, and package-lock.json back to master as chore(release): X.Y.Z [skip ci], so both the version and the changelog history persist in the repository.
5. Building the XAR (npm run build).
6. Creating a Git tag (vX.Y.Z) on the release commit, creating a corresponding GitHub Release, and uploading the XAR as a release asset.
7. Publishing the XAR to the eXist-db public package repository: the published release triggers the Publish to public-repo workflow, which downloads the XAR from the GitHub Release and uploads it with the org's repository credentials. A failed or historical upload can be redone any time by dispatching that workflow manually with the release tag.

What contributors need to do

• Write Conventional Commits. A commitlint + husky commit-msg hook enforces this locally (@commitlint/config-conventional). The commit type determines the version bump:
  • feat: → minor bump
  • fix:, perf: → patch bump
  • any commit with a BREAKING CHANGE: footer or a ! after the type (e.g. feat!:) → major bump
  • chore:, docs:, ci:, build:, style:, refactor:, test: → no release (cosmetic / housekeeping)
• That's it. No version bump, no tag creation, no manual release commit.

Why the release pipeline commits back to master

Following a community vote, monex persists the released version and changelog in the repository: each release ends with a chore(release): X.Y.Z [skip ci] commit updating repo.xml.tmpl, package.json, and package-lock.json, and the tag points at that commit. This keeps the <changelog> in repo.xml.tmpl complete across releases — with the earlier in-memory-only approach, each generated <change> entry was lost after its release, so shipped XARs were missing the entries of all previous automated releases (see #453).

The push is made by the org's exist-bot GitHub App, which is a bypass actor for the protection on master: the release job mints a short-lived installation token for it with actions/create-github-app-token and hands that to semantic-release. The default GITHUB_TOKEN cannot pass the branch protection (and the built-in github-actions identity cannot be made a ruleset bypass actor), which is why a dedicated App identity is used instead of a PAT. Earlier, master was pinned to 0.0.0-development with the version set only in-memory on the CI runner, matching @existdb/xst, @existdb/node-exist, and @existdb/gulp-exist — see #386 and #396 for that history.

What release managers need to do

Nothing routine — pushes to master are released automatically.

If the release pipeline fails (check the Release job in the Actions tab) the commit history is still intact and re-running the job is safe: semantic-release is idempotent. 2. The eXist-db Public EXPath Repository