Document new statement reset behavior

directory.json

@@ -864,10 +864,6 @@
       "title": "Collector crashes",
       "path": "/docs/install/troubleshooting/collector_crash"
     },
-    "install/troubleshooting/collector_times_out": {
-      "title": "Collector times out",
-      "path": "/docs/install/troubleshooting/collector_times_out"
-    },
     "install/troubleshooting/column_stats_helper": {
       "title": "Resolving the \"Limited access to table column statistics\" warning",
       "path": "/docs/install/troubleshooting/column_stats_helper"
@@ -888,6 +884,10 @@
       "title": "Amazon RDS: Resolving the \"pg_stat_statements must be loaded via shared_preload_libraries\" error",
       "path": "/docs/install/troubleshooting/rds_pg_stat_statements_shared_preload_libraries"
     },
+    "install/troubleshooting/reset_stat_statements": {
+      "title": "Reducing memory usage and query text unavailable",
+      "path": "/docs/install/troubleshooting/reset_stat_statements"
+    },
     "log-insights": {
       "title": "pganalyze Log Insights",
       "path": "/docs/log-insights"

install/troubleshooting.mdx

@@ -7,7 +7,7 @@ backlink_title: 'Installation Guide'
 This section provides helpful information about troubleshooting your pganalyze installation:
 
  * [Collector crashing](/docs/install/troubleshooting/collector_crash)
- * [Collector times out](/docs/install/troubleshooting/collector_times_out)
+ * [Reducing memory usage and query text unavailable](/docs/install/troubleshooting/reset_stat_statements)
  * [Amazon RDS: Resolving the "pg\_stat\_statements must be loaded via shared\_preload\_libraries" error](/docs/install/troubleshooting/rds_pg_stat_statements_shared_preload_libraries)
  * [Resolving the "Limited access to table column statistics" warning](/docs/install/troubleshooting/column_stats_helper)
  * [Resolving the "missing extended stats monitoring helper functions" warning](/docs/install/troubleshooting/ext_stats_helper)

install/troubleshooting/collector_crash.mdx

@@ -8,6 +8,10 @@ If you find the collector crashing, the most likely cause is running out of memo
 a small instance size by default as that is enough for the typical case, but with a very large
 schema or a large or diverse query workload, that may not be sufficient.
 
+Before increasing the collector's memory limit, you may want to enable
+[automatic pg_stat_statements resets](/docs/install/troubleshooting/reset_stat_statements)
+to reduce memory usage from query text.
+
 Collector memory may be limited either through available instance memory, or through systemd (if
 your platform uses it).
 

install/troubleshooting/reset_stat_statements.mdx

@@ -0,0 +1,46 @@
+---
+title: Reducing memory usage and query text unavailable
+backlink_href: /docs/install/troubleshooting
+backlink_title: 'Installation Troubleshooting'
+---
+
+If the collector is using too much memory or `<query text unavailable>` is showing up in pganalyze,
+you may want to set up an automatic reset of pg_stat_statements.
+
+## &lt;query text unavailable&gt;
+
+Some versions of Postgres aren't able to accurately normalize queries (e.g. those with variable bind params),
+leading to many duplicate entries that often have very low call counts. When `pg_stat_statements.max` is reached,
+Postgres will deallocate (remove) the entries with the lowest call count. In periods of high database activity
+this can happen so so quickly that the collector isn't able to capture the query text, causing
+`<query text unavailable>` to show up in pganalyze.
+
+This can be addressed by enabling the Maximum Query Stats Reset Frequency setting. We recommend a setting of
+"Every 1 hour" unless you're specifically concerned about lock contention on a very busy database. This enables
+automatic pg_stat_statments resets to be done once the statement space is 90% full (so a deallocation would occur soon),
+but resets will not occur more often than the frequency setting you choose.
+
+## High memory usage
+
+Every 10 minutes, the collector loads the query text from pg_stat_statements into memory in order to normalize and
+fingerprint it. This is a very expensive step and can result in the collector crashing from running out of memory.
+To address that, when resets are enabled with the Maximum Query Stats Reset Frequency setting, the collector will
+also perform a reset if the size of the query text grows beyond 250 MB. You can optionally increase that limit
+using the Maximum Query Size Before Next Reset setting.
+
+## Setup
+
+Collector version 0.70.0 or later is required.
+
+After enabling the Maximum Query Stats Reset Frequency setting on the server settings page (and optionally tuning
+    Maximum Query Size Before Next Reset), the collector will automatically start performing resets when needed.
+You should see evidence of that in the collector logs.
+
+If the collector fails to reset with permissions errors, you may need to define this function:
+
+<CodeBlock language="sql">
+{`CREATE OR REPLACE FUNCTION pganalyze.reset_stat_statements() RETURNS SETOF void AS
+$$
+  /* pganalyze-collector */ SELECT * FROM public.pg_stat_statements_reset();
+$$ LANGUAGE sql VOLATILE SECURITY DEFINER;`}
+</CodeBlock>

install/troubleshooting/toc.yml

@@ -2,8 +2,8 @@
   items:
   - name: Collector crashes
     href: install/troubleshooting/collector_crash
-  - name: Collector times out
-    href: install/troubleshooting/collector_times_out
+  - name: Reducing memory usage and query text unavailable
+    href: install/troubleshooting/reset_stat_statements
   - name: 'Resolving the "Limited access to table column statistics" warning'
     href: install/troubleshooting/column_stats_helper
   - name: 'Resolving the "missing extended stats monitoring helper functions" warning'