This page describes Calíope 1.5, the version I am building right now. 1.4 is on the App Store for the Mac, iPad, iPhone, Apple Watch, Apple TV and Apple Vision Pro. 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, MariaDB and SQL Server 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 Monitoring Setup —the gear icon (⚙) once there is something to show— to open the settings.
3. Turn on Enable Monitoring 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 Save & 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 Data 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, from Last hour to Last 30 days.
- The engine status —a green, yellow or red dot with its label: Running, Starting…, Retrying, No storage…— shows whether monitoring is active, starting up, or cannot reach the storage server. An orange triangle beside it means the last poll of the selected server failed, and its tooltip says why.
- 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.
Arranging the charts:
- The sliders button (Customize health charts layout) puts two arrows and an eye on every chart. The arrows move a chart one place —you can also drag it—, the eye hides it, and hidden charts wait at the bottom, under Hidden Charts, until you click them.
- The ↺ button (Reset layout) puts every chart back in its default place, after asking.
- The checkmark finishes. The layout is remembered and, with iCloud sync on, travels to your other devices.
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: the four with a single value draw a line over a filled area, and Network and DML draw one line per series. 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 statements running at that instant: the threads executing a query (Query or Execute in SHOW PROCESSLIST; on PostgreSQL, the sessions in the active state; on SQL Server, the user sessions with a request under way). Idle connections, replication threads and the server's own daemons do not count. 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 says This server does not measure it: PostgreSQL, for instance, counts no network traffic and does not break statements down by verb, and its QPS counts transactions rather than statements. SQL Server counts neither network bytes nor rows, does not break statements down by verb either, and its QPS counts batches.
- 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 Last 30 days 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: Health Monitor › Monitoring Setup
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
- The ⚙︎ button in the top bar of the Health Monitor, on macOS, iPad and iPhone. While nothing is set up, the bar and the empty screen show it as Monitoring Setup.
- Every change is saved as you make it; Close just closes the dialog.
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 Save & 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: Schema ready 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 checkbox to enable/disable it without deleting the config, its interval, a button with that server's own health thresholds, and a − button to remove it.
- The storage server cannot be added as a monitored server of itself: the list does not offer it.
- Below the list, Health thresholds decide when a server turns to warning or critical on the Calíope dashboard on your Apple TV.
4. Data Retention
- Dropdown with presets (7, 14, 30, 60, 90 and 180 days, and No limit).
- No limit never deletes and shows an orange warning — remember that server_snapshots grows on every tick.
- Cleanup runs on every engine start and once a day while the app is open.
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;).