Self-Tracking

Open as Markdown

chmonitor writes events to a ClickHouse table as users interact with the dashboard. This self-tracking data lets you audit dashboard usage, debug unexpected behavior, and see which pages and queries are most active.

What it records

Every page visit, query execution, and action in the dashboard writes a row to the events table. Recorded fields include the event type, page path, host index, timestamp, and relevant metadata (e.g. query fingerprint, table name).

A companion monitoring_findings table stores persistent findings recorded by the AI agent across sessions.

Configuration

Variable	Default	Description
`EVENTS_TABLE_NAME`	`system.monitoring_events`	Full table name for self-tracking events. Override to use a different database or table.
`CLICKHOUSE_DATABASE`	`system`	Default database for app-owned tables when `EVENTS_TABLE_NAME` is not explicitly set.

The table is created automatically on first use if it does not exist and the configured ClickHouse user has CREATE TABLE permission on the target database.

Change the table location

To write events to a non-system database:

CLICKHOUSE_DATABASE=chmonitor
## EVENTS_TABLE_NAME defaults to chmonitor.monitoring_events

Or set the full table name directly:

EVENTS_TABLE_NAME=my_db.dashboard_events

Disable self-tracking

chmonitor does not currently have a single flag to disable all event writes. To suppress writes, point EVENTS_TABLE_NAME at a Null-engine table:

CREATE TABLE my_db.monitoring_events_null AS system.monitoring_events
ENGINE = Null;

EVENTS_TABLE_NAME=my_db.monitoring_events_null

Inserts succeed instantly and no data is retained.

ClickHouse grants required

The configured CLICKHOUSE_USER needs:

GRANT INSERT ON system.monitoring_events TO monitoring_user;
-- Or on the custom table if EVENTS_TABLE_NAME is overridden:
GRANT CREATE TABLE, INSERT ON my_db.* TO monitoring_user;

If the user lacks INSERT permission, event writes fail silently and the dashboard continues to work normally.

Environment Variables — Query Execution — EVENTS_TABLE_NAME and CLICKHOUSE_DATABASE.
Queries History — how the dashboard reads system.query_log for history pages.