This page describes Calíope 1.5, the version we are building right now. 1.4 is finished and in App Review, and the store serves 1.3 on the Mac and 1.2 on iPad. The changelog says which version each feature landed in.
Adds an “Open in Calíope” button to every topic. It only works with the app installed.
Collects and visualizes historical metrics from one or more of your servers: QPS, threads, cache hit rate, network, DML, and more. Data is stored on a centralized server of your choosing and remains available even after closing the app.
Where it is: Workspace › Tools › Health
The Health Monitor lets you track the performance of several of your servers over time. Unlike the Dashboard (which shows real-time metrics for the currently connected server), the Health Monitor stores historical snapshots in a centralized store, accessible from any session and shared among team members.
Architecture:
- Storage server — a server where Calíope creates the caliope_monitoring store with its snapshot tables. On MySQL and MariaDB it is a database; on PostgreSQL it is a schema inside the database the profile points at, so two profiles on the same server pointing at different databases are two different stores. It must be accessible to all users who want to query the history.
- Monitored servers — the servers from which metrics are collected. These can be different from the storage server.
- Monitoring engine — runs in the background from the moment the app launches; the tab does not need to be open for monitoring to work.
Initial setup:
1. Open the Health Monitor tab from the workspace navigation bar (heart icon).
2. Tap the gear icon (⚙) to open the settings.
3. Enable the Enable monitoring toggle at the top of the panel. You can disable it at any time to completely stop metric collection without losing your configuration.
4. Under Storage server, select an existing connection profile and tap Provision. Calíope automatically creates the caliope_monitoring store and all required tables. The user must have the CREATE privilege on the selected server.
5. Under Monitored servers, tap + to add each server you want to monitor. For each server you can define:
- Alias — a friendly name to identify it in charts.
- Interval — collection frequency: 15 s, 30 s, 1 min (default), 5 min, 15 min, 30 min, or 1 hour.
- Active — toggle to pause monitoring for a server without removing it.
6. Under Retention, choose how many days to keep data (7, 14, 30, 60, 90, or 180 days). The "No limit" option keeps all data indefinitely.
7. Close the settings. The engine starts automatically if monitoring is enabled.
Background operation:
Monitoring continues while the app is open, regardless of which tab is active. If you close and reopen the app, the engine restarts automatically on launch.
Visualization:
- Select the server in the top bar selector to view its metrics.
- Choose the time range: 1 h, 6 h, 24 h, 7 d, or 30 d.
- Engine status indicators (green/yellow/red dot) show whether monitoring is active, starting up, or disconnected from the storage server.
- The ↻ button manually reloads data from the storage server.
- The ⏱ button (clock with arrow) enables auto-refresh every 30 seconds: charts reload automatically without needing to tap ↻. On macOS, the label 30 s appears next to the icon when active. Disable it if you want a static view to inspect data without it changing.
Description of each chart: connected threads, QPS, cache hit rate, active processes, network (bytes/s), and DML per second.
Where it is: Workspace › Tools › Health
The monitor displays six time-series charts, each with a fill area and line to make trends easy to read. You can tap or click any point on a chart to see the exact value at that moment.
Connected Threads
Number of open connections at that moment. A value close to the max_connections limit indicates a risk of saturation.
QPS — Queries Per Second
Rate of queries executed per second, calculated as the difference in Queries between consecutive snapshots divided by the interval. Reflects the overall server load.
Cache hit rate (%)
Percentage of read requests served from the server's cache without going to disk. Calculated as:
(1 − Δ disk reads / Δ read requests) × 100
Each engine publishes those two counters under its own names, and a server that publishes neither leaves the chart empty.
A value sustained below 95% indicates the cache is insufficient for the workload and should be increased.
Active Processes
Number of queries running at that instant (SHOW PROCESSLIST, excluding threads in Sleep state). A high, persistent value suggests slow queries or locks.
Network (bytes/s)
Network traffic to and from the server:
- RX — bytes received per second (Bytes_received).
- TX — bytes sent per second (Bytes_sent).
Useful for detecting queries that transfer abnormally large volumes of data.
DML/s — Data Modification Statements
Rate of DML statements per second, broken down into:
- SELECT — reads.
- INSERT — inserts.
- UPDATE — updates.
- DELETE — deletes.
A sudden spike in INSERT/UPDATE/DELETE may indicate active batch or ETL processes.
General interpretation:
- Charts show values calculated from the server's cumulative counters, so they represent per-second rates, not absolute totals.
- Not every engine publishes every counter. What a server does not measure is stored empty and its chart stays blank: PostgreSQL, for instance, counts no network traffic and does not break statements down by verb, and its QPS counts transactions rather than statements.
- Short sampling intervals (15 s, 30 s) produce more detailed charts but generate more data on the storage server.
- Configurable retention (see Server Health Monitor) controls the visible period in the 30 d range.
Keywords: connected threads, threads_connected, qps, queries per second, cache hit rate, innodb hit rate, buffer pool, active processes, processlist, bytes_received, bytes_sent, com_select, com_insert, com_update, com_delete, dml, network, throughput, time series, chart, metrics
How to enable monitoring, pick the storage server, add monitored servers, and set the retention.
Where it is: Server Health › Configure
Calíope's Server Health Monitor keeps a history of metrics periodically sampled from your servers. That history lives in its own schema, caliope_monitoring, hosted on a server you choose — not inside the app.
Open the setup dialog
- macOS: menu Window › Server Health › Configure… or the ⚙︎ button in the top bar of the Server Health view.
- iPad: in the Server Health tab, tap the ⚙︎ button in the top bar.
1. Enable monitoring
- Toggle at the top of the dialog. When you turn it on, MonitoringEngine starts in the background; when off, it stops.
2. Storage server
- Pick, from the grouped picker, which of your profiles will host the caliope_monitoring schema.
- It can be the same server you monitor or a dedicated one (recommended for production).
- Tap Provision so Calíope creates the store and its required tables — it is idempotent (uses CREATE … IF NOT EXISTS), so you can safely re-run it if you dropped something manually.
- Visual state: Provisioned ✓ in green when it works, or a red label with the error if the connection fails.
Tables created
- caliope_monitoring.monitoring_config — schema version, retention, and last cleanup timestamp.
- caliope_monitoring.monitored_servers — servers registered as monitored.
- caliope_monitoring.server_snapshots — time-series snapshots (uptime, threads, cache, statements by verb, traffic, active processes, longest query, etc.).
- caliope_monitoring.collection_errors — collection errors, useful for diagnostics.
3. Monitored servers
- + button to add one. Select the profile, give it a readable alias, and pick the polling interval (15 s, 30 s, 1 min, 5 min, etc.).
- Each row has a toggle to enable/disable without deleting the config, and a − button to remove it.
- The storage server cannot be added as a monitored server of itself.
4. Retention
- Dropdown with presets (7, 14, 30, 60 days, etc.).
- The value 0 means "never delete" and shows an orange warning — remember that server_snapshots grows on every tick.
- Cleanup runs on every engine start and at regular intervals during the session.
Security notes
- All connections to the storage server use the same credentials stored in the Keychain for that profile (optional Keychain sync).
- If you delete the app or hit Delete all my data, the app stops writing; the caliope_monitoring.* tables remain on the server until you drop them manually (DROP DATABASE caliope_monitoring;).