chmonitorSelf-Tracking
chmonitor writes its own usage events to a ClickHouse table — configure the target table, required grants, and how to suppress writes.
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.
Configure
Set the target table
Point self-tracking at whichever database and table you want.
| 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.
Grant the required permissions
The configured CLICKHOUSE_USER needs INSERT on the events table:
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.
Change the table location
To write events to a non-system database:
CLICKHOUSE_DATABASE=chmonitorEVENTS_TABLE_NAME then defaults to chmonitor.monitoring_events.
Or set the full table name directly:
EVENTS_TABLE_NAME=my_db.dashboard_eventsDisable 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_nullInserts succeed instantly and no data is retained.