diff --git a/content/references/advanced/_index.md b/content/references/advanced/_index.md index 426ae51..ff4abb8 100644 --- a/content/references/advanced/_index.md +++ b/content/references/advanced/_index.md @@ -14,3 +14,4 @@ The following sub-pages give an overview over the most important ones and explai * [pgvector compatibility](pgvector) * [Prepared statements](prepare) * [Tables stored on S3](s3) +* [Load history collection](loadhistory) diff --git a/content/references/advanced/loadhistory.md b/content/references/advanced/loadhistory.md new file mode 100644 index 0000000..93bc904 --- /dev/null +++ b/content/references/advanced/loadhistory.md @@ -0,0 +1,123 @@ +--- +title: Load History System Tables +weight: 20 +--- + +CedarDB collects metrics on system usage. These metrics include CPU usage, network usage, +disk usage for the disk the database resides on, as well as some CedarDB-internal metrics. + +These metrics are exposed through system tables, and can be queried through sql: + +```sql +select * from cedardb_cpu_load_history +order by timestamp desc +limit 10; +``` + +```text + timestamp | cpu_load +-------------------------------+----------- + 2026-09-08 14:09:51.552458+02 | 2.1 + 2026-09-08 14:09:41.552465+02 | 2.06 + 2026-09-08 14:09:31.552557+02 | 1.37 + 2026-09-08 14:09:21.552383+02 | 1.5500001 + 2026-09-08 14:09:11.552349+02 | 1.4 + 2026-09-08 14:09:01.552454+02 | 1.5799999 + 2026-09-08 14:08:51.552497+02 | 1.5899999 + 2026-09-08 14:08:41.552507+02 | 1.77 + 2026-09-08 14:08:31.552545+02 | 2.23 + 2026-09-08 14:08:21.552451+02 | 2.5500002 +(10 rows) +``` + +{{< callout type="info" >}} +Load history collection is an enterprise feature and requires an enterprise license to use. +{{< /callout >}} + +## Configuration + +Both the interval in which these metrics are collected and the number of measurements to retain can be configured. + +Setting `loadhistory.interval` specifies the time between two measurements (in ms). The default value for this setting is `10000` (10 seconds). +Setting this to `0` disables load history collection altogether. + +Setting `loadhistory.retention` specifies the number of measurements that are stored before they will be dropped. The default value for this setting is `8640`. +For an interval of 10 seconds, this will retain values for 24 hours. + +## Metrics and Tables + +All `cedardb_*_load_history` tables have as their first column the `timestamp` of when the measurement was taken. + +### CPU load + +CedarDB makes available the CPU usage through the system table `cedardb_cpu_load_history`. + +`cpu_load` +: CPU usage in percent + +### Connection activity + +CedarDB makes available metrics on connections through the system table `cedardb_connection_load_history`. + +`total` +: Total number of connections to the database open + +`active` +: Connections currently executing a statement + +`idle` +: Connections currently not inside a transaction + +`idle_in_transaction` +: Connections with an active transaction, but not currently executing a statement + +### Memory usage + +Since CedarDB is optimized to make good use of memory, it uses 90% of system memory by default. Thus, it doesn't report +usage of system RAM, but rather the pressure on the buffer manager. This metric is exposed through the system table +`cedardb_memory_load_history`. + +`buffer_pressure` +: The last known pressure estimate of the buffer manager + +You can read more about CedarDB's technology [on the docs page](../../../technology). + +### Disk usage + +CedarDB makes available metrics on the disk that the database resides on through the system table `cedardb_disk_load_history`. + +All metrics are in bytes. + +`disk_size` +: The total size of the disk + +`free_space` +: The total free space left on the disk + +`db_file_size` +: The size of the `db` file + +`page_file_size` +: The size of the `db.pages` file + +`tmpfiles_dir_size` +: The combined size of all files inside the `tmpfiles` directory + +`wal_files_size` +: The combined size of all `.wal` files + +`read_bytes` +: The number of bytes read by CedarDB since startup + +`write_bytes` +: The number of bytes written by CedarDB since startup + +### Network I/O + +CedarDB makes available metrics on network usage through the system table `cedardb_network_load_history`. + +`read_bytes` +: The total number of bytes read from any network interface (except `loopback`) since OS startup + +`write_bytes` +: The total number of bytes written to any network interface (except `loopback`) since OS startup