From 31fe5121c785aba57f13da4b7246dfae509072f0 Mon Sep 17 00:00:00 2001
From: Rich Loveland <rich@cockroachlabs.com>
Date: Fri, 9 Jan 2026 15:36:03 -0500
Subject: [PATCH] Document AC setting always_use_short_sample_period

Fixes DOC-15826

Summary of changes:

- Add a new 'Cluster settings' section to the 'Recommended production
  settings' page

- Manually add the `goschedstats.always_use_short_sample_period.enabled`
  cluster setting to the cluster settings page

- Update the mention of the above setting on the AC page to link to the
  other updated sections

NB. These changes will be ported to v23.2, v24.1, v24.3, and v25.2
docs. (This cluster setting was changed to default to `true` in v25.3)
---
 src/current/v24.1/admission-control.md               |  2 +-
 src/current/v24.1/cluster-settings.md                | 12 ++++++++++++
 src/current/v24.1/recommended-production-settings.md |  6 ++++++
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/src/current/v24.1/admission-control.md b/src/current/v24.1/admission-control.md
index df357eb349d..e57a49b142a 100644
--- a/src/current/v24.1/admission-control.md
+++ b/src/current/v24.1/admission-control.md
@@ -135,7 +135,7 @@ COMMIT;
 
 ## Considerations
 
-To prevent unnecessary queuing in admission control CPU queues, set the `goschedstats.always_use_short_sample_period.enabled` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to `true` for any production cluster.
+To prevent unnecessary queuing in admission control CPU queues, set the `goschedstats.always_use_short_sample_period.enabled` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}#setting-goschedstats-always-use-short-sample-period-enabled) to `true` for any [production cluster]({% link {{ page.version.version }}/recommended-production-settings.md %}).
 
 [Client connections]({% link {{ page.version.version }}/connection-parameters.md %}) are not managed by the admission control subsystem. Too many connections per [gateway node]({% link {{ page.version.version }}/architecture/sql-layer.md %}#gateway-node) can also lead to cluster overload. 
 
diff --git a/src/current/v24.1/cluster-settings.md b/src/current/v24.1/cluster-settings.md
index 8bb83a25a09..1d4f9ce0a72 100644
--- a/src/current/v24.1/cluster-settings.md
+++ b/src/current/v24.1/cluster-settings.md
@@ -28,6 +28,18 @@ These cluster settings have a broad impact on CockroachDB internals and affect a
 
 {% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/settings/settings.html %}
 
+<a name="setting-goschedstats-always-use-short-sample-period-enabled"></a>
+
+<table>
+  <tr>
+    <td><code>goschedstats.always_use_short_sample_period.enabled</code></td>
+    <td>boolean</td>
+	<td>false</td>
+	<td>When set to true, the system uses a shorter sampling period of runnable queue lengths. This setting should always be enabled for <a href="recommended-production-settings.html">production clusters</a> to help prevent unnecessary queuing in the <a href="admission-control.html">admission control</a> subsystem.</td>
+    <td>Advanced/Self-Hosted</td>
+  </tr>
+</table>
+
 ## View current cluster settings
 
 Use the [`SHOW CLUSTER SETTING`]({% link {{ page.version.version }}/show-cluster-setting.md %}) statement.
diff --git a/src/current/v24.1/recommended-production-settings.md b/src/current/v24.1/recommended-production-settings.md
index 75f48a67b2c..7b9852ef147 100644
--- a/src/current/v24.1/recommended-production-settings.md
+++ b/src/current/v24.1/recommended-production-settings.md
@@ -28,6 +28,12 @@ Existing deployments that have THP enabled using the `always` option should chan
 
 The method for permanently changing the THP setting across reboots depends on the operating system. For Red Hat Enterprise Linux, refer to the [Red Hat documentation](https://access.redhat.com/solutions/46111).
 
+## Cluster settings
+
+This section lists cluster setting changes that are recommended for production deployments:
+
+- To prevent unnecessary queuing in [admission control]({% link {{ page.version.version }}/admission-control.md %}) CPU queues, set the `goschedstats.always_use_short_sample_period.enabled` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}#setting-goschedstats-always-use-short-sample-period-enabled) to `true` for any production cluster.
+
 ## Hardware
 
 {% include {{ page.version.version }}/prod-deployment/terminology-vcpu.md %}