CNS-139: docs: document query history and statement logging for self-managed

[jubrad]

DNM until 9/2/26

Query history is becoming available and enabled by default in self-managed deployments, but the docs said nothing about it. Self-managed operators had no guidance on the shipped sample rate, how to change it, or what it costs.

Linear: https://linear.app/materializeinc/issue/CNS-139/docs-document-query-history-and-statement-logging-for-self

Changes

• New page self-managed-deployments/query-history.md: what query history is and who can see it, the two parameters that bound how much is collected, how to tune each via the Helm chart and via system parameters, and the CPU/storage cost of each.
• console/monitoring.md: notes that query history is sampled and links to the new page.
• reference/system-catalog/mz_internal.md: no longer says the max sample rate is "set by Materialize and cannot be changed by users". Now distinguishes Cloud (Materialize-controlled) from self-managed (operator-controlled).
• transform-data/troubleshooting.md: this page claimed outright that "the sampling rate is not user-configurable", which directly contradicts the new page. Also corrected its "three days" window to 24 hours, which is what mz_recent_activity_log actually retains.
• configuration-system-parameters.md: adds both statement-logging parameters to the parameter list.

Notes for the reviewer

Merge after #38406 (CNS-136). That PR exposes the chart values this page documents. Until it lands, the chart still passes --disable-statement-logging, so "enabled by default" describes the post-#38406 chart, not main today. Documented values track #38406's latest revision: statementLoggingMaxSampleRate: 0.99 and statementLoggingTargetDataRate unset (inheriting 2071 B/s). The console side is #38407/#38408.

Two behaviors are worth a careful look, since both are easy to get wrong and I verified them against the source rather than assuming:

1. Precedence. The chart values reach environmentd as --system-parameter-default=..., so they are only defaults. A ConfigMap or ALTER SYSTEM SET value is upserted into the catalog and wins. Undoing an override needs both removing the ConfigMap key and ALTER SYSTEM RESET: removing the key alone leaves the last synced value in the catalog, and resetting alone gets reapplied by the 1s sync loop.
2. The sample rate is not the storage lever. statement_logging_target_data_rate throttles sampled statements, so a sample rate of 1.0 does not record everything, and lowering the sample rate does not lower the ceiling on what statement logging stores. Relatedly, the statement history collections are never truncated, so storage grows for the life of the instance even though the view only shows 24 hours. The page therefore points operators at the data rate for storage concerns and at the sample rate only for environmentd CPU.

ALTER SYSTEM SET for these parameters requires mz_system, not just any superuser, since they are not user-modifiable. The page says so.

Testing

ci/test/lint-docs.sh locally: both hugo builds clean, htmltest reports only 2 pre-existing AWS Glue link errors also present on the base commit, and lint-docs-catalog.sh shows no .slt drift from the mz_internal.md edits.

🤖 Generated with Claude Code