fix: Add clickhouse tuning steps

content/nim/fundamentals/tech-specs.md

@@ -132,6 +132,10 @@ The table below shows the estimated storage requirements for **NGINX OSS**, base
 |                       | 250       | 14               | 4 GiB                            |
 {{</bootstrap-table>}}
 
+## ClickHouse tuning {#clickhouse-tuning}
+The default ClickHouse configuration works efficiently with NGINX Instance Manager.  
+If you change the configuration and ClickHouse runs out of memory, see the [ClickHouse configuration guide]({{< ref "/nim/system-configuration/configure-clickhouse.md#clickhouse-tuning" >}}) to adjust the settings.
+
 ## Firewall ports {#firewall}
 
 NGINX Instance Manager and NGINX Agent use the Unix domain socket by default and proxy through the gateway on port `443`.

content/nim/system-configuration/configure-clickhouse.md

@@ -69,3 +69,133 @@ When metrics are turned off:
 - The web interface no longer shows metrics dashboards. Instead, it displays a message explaining that metrics are turned off.
 - Metrics-related API endpoints return a 403 error.
 - All other NGINX Instance Manager features continue to work as expected.
+
+## ClickHouse tuning {#clickhouse-tuning}
+
+The default ClickHouse configuration works efficiently with NGINX Instance Manager. If you change the configuration and ClickHouse runs out of memory, use the following steps.
+
+ClickHouse has system tables that provide logs and telemetry for monitoring and debugging. These are not user activity logs but internal diagnostic logs. The following tables can cause memory issues if not managed:
+
+Records detailed execution traces and profiling data. Useful for query debugging and performance analysis.
+
+You can change the settings for `trace_log` in `/etc/clickhouse-server/config.xml` under the `<trace_log>` section. The `flush_interval_milliseconds` setting controls how often data is flushed from memory to the table. The default is `7500`. Lowering this value can increase captured rows and use more memory.
+
+Default settings for trace_log is as follows
+
+```xml
+<trace_log>
+    <database>system</database>
+    <table>trace_log</table>
+    <partition_by>toYYYYMM(event_date)</partition_by>
+    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
+    <max_size_rows>1048576</max_size_rows>
+    <reserved_size_rows>8192</reserved_size_rows>
+    <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
+    <flush_on_crash>false</flush_on_crash>
+    <symbolize>false</symbolize>
+</trace_log>
+```
+
+To check memory use by each table:
+
+```sql
+SELECT
+    database,
+    table,
+    formatReadableSize(sum(bytes_on_disk)) AS total_size
+FROM system.parts
+GROUP BY database, table
+ORDER BY sum(bytes_on_disk) DESC;
+```
+To configure a time to live (TTL):
+
+Update the interval value (for example, `7 DAY`) to set how long records are kept and prevent the table from growing too large:
+
+```sql
+ALTER TABLE system.trace_log
+MODIFY TTL event_time + INTERVAL 7 DAY;
+```
+To free memory immediately:
+
+Update the interval value (for example, `30 DAY`) to control how many records to delete.
+
+```sql
+ALTER TABLE system.trace_log DELETE WHERE event_time < now() - INTERVAL 30 DAY;
+### metric_log
+
+Stores historical metrics from `system.metrics` and `system.events`. Useful for analyzing performance trends. Too much historical data can cause memory issues.
+
+Default settings:
+
+```xml
+<metric_log>
+   <database>system</database>
+   <table>metric_log</table>
+   <flush_interval_milliseconds>7500</flush_interval_milliseconds>
+   <max_size_rows>1048576</max_size_rows>
+   <reserved_size_rows>8192</reserved_size_rows>
+   <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
+   <collect_interval_milliseconds>1000</collect_interval_milliseconds>
+   <flush_on_crash>false</flush_on_crash>
+</metric_log>
+```
+
+Check table memory use:
+
+```sql
+SELECT
+   database,
+   table,
+   formatReadableSize(sum(bytes_on_disk)) AS total_size
+FROM system.parts
+GROUP BY database, table
+ORDER BY sum(bytes_on_disk) DESC;
+
+Set TTL:
+
+```sql
+ALTER TABLE system.metric_log
+MODIFY TTL event_time + INTERVAL 7 DAY;
+
+Free memory immediately:
+
+```sql
+ALTER TABLE system.metric_log DELETE WHERE event_time < now() - INTERVAL 30 DAY;
+
+### text_log
+
+Stores general logs such as warnings, errors, system messages, and query events. You can control what is logged using the `text_log.level` server setting.
+
+Default settings:
+
+```xml
+<text_log>
+   <database>system</database>
+   <table>text_log</table>
+   <flush_interval_milliseconds>7500</flush_interval_milliseconds>
+   <max_size_rows>1048576</max_size_rows>
+   <reserved_size_rows>8192</reserved_size_rows>
+   <buffer_size_rows_flush_threshold>524288</buffer_size_rows_flush_threshold>
+   <flush_on_crash>false</flush_on_crash>
+   <level>trace</level>
+</text_log>
+You can use the below command to view the current memory occupied by each table in the clickhouse database using the below command from clickhouse-client.
+```shell
+SELECT
+    database,
+    table,
+    formatReadableSize(sum(bytes_on_disk)) AS total_size
+FROM system.parts
+GROUP BY database, table
+ORDER BY sum(bytes_on_disk) DESC;
+```
+
+If it is observed that this table is taking more memory, you can set the TTL(Time to Live) so that old records will be deleted after the TTL time. The TTL setting makes sure your table does not grow uncontrollably and delete the old records automatically after the TTL.
+```shell
+ALTER TABLE system.text_log
+MODIFY TTL event_time + INTERVAL 7 DAY;
+```
+You can also relieve the memory immediately if its running very low using the below command. Change the interval in the command to how many days of records you want to retain and delete the remaining records.
+```shell
+ALTER TABLE system.text_log DELETE WHERE event_time < now() - INTERVAL 30 DAY;
+```