[DOC-5572] Document CPU exhaustion scenario and workaround when SCRAM…

… Authentication is enabled (cockroachdb#15254) * [DOC-5572] Document CPU exhaustion scenario and workaround when SCRAM Authentication is enabled - Also update some section headings to use non-gerund verbs, per the style guide Co-authored-by: Ryan Kuo <[email protected]>
MozzieWen · Oct 17, 2022 · 15871dc · 15871dc
1 parent e094de4
commit 15871dc
Show file tree

Hide file tree

Showing 6 changed files with 155 additions and 93 deletions.
diff --git a/_includes/v22.1/scram-authentication-recommendations.md b/_includes/v22.1/scram-authentication-recommendations.md
@@ -0,0 +1,4 @@
+- Test and adjust your workloads in batches when migrating to SCRAM authentication.
+- Start by enabling SCRAM authentication in a testing environment, and test the performance of your client application against the types of workloads you expect it to handle in production before rolling the changes out to production.
+- Limit the maximum number of connections in the client driver's connection pool.
+- Limit the maximum number of concurrent transactions the client application can issue.
diff --git a/_includes/v22.2/scram-authentication-recommendations.md b/_includes/v22.2/scram-authentication-recommendations.md
@@ -0,0 +1,4 @@
+- Test and adjust your workloads in batches when migrating to SCRAM authentication.
+- Start by enabling SCRAM authentication in a testing environment, and test the performance of your client application against the types of workloads you expect it to handle in production before rolling the changes out to production.
+- Limit the maximum number of connections in the client driver's connection pool.
+- Limit the maximum number of concurrent transactions the client application can issue.
diff --git a/v22.1/error-handling-and-troubleshooting.md b/v22.1/error-handling-and-troubleshooting.md
@@ -67,6 +67,23 @@ However, you may need to access the underlying cluster to troubleshoot issues wh
 
 For more information about how to troubleshoot cluster-level issues, see [Troubleshoot Cluster Setup](cluster-setup-troubleshooting.html).
 
+## Troubleshoot SQL client application problems
+
+### High client CPU load or connection pool exhaustion when SCRAM Password-based Authentication is enabled
+
+When [SASL/SCRAM-SHA-256 Secure Password-based Authentication](security-reference/scram-authentication.html) (SCRAM Authentication) is enabled on a cluster, some additional CPU load is incurred on client applications, which are responsible for handling SCRAM hashing. It's important to plan for this additional CPU load to avoid performance degradation, CPU starvation, and connection pool exhaustion on the client. For example, the following set of circumstances can exhaust the client application's resources:
+
+1. SCRAM Authentication is enabled on the cluster.
+1. The client driver's connection pool has no defined maximum number of connections.
+1. The client application issues transactions concurrently.
+
+In this situation, each new connection uses more CPU on the client application server than connecting to a cluster without SCRAM Authentication enabled. Because of this additional CPU load, each concurrent transaction is slower, and a larger quantity of concurrent transactions can accumulate, in conjunction with a larger number of concurrent connections. In this situation, it can be difficult for the client application server to recover.
+
+To mitigate against this situation, Cockroach Labs recommends that you:
+
+{% include_cached {{page.version.version}}/scram-authentication-recommendations.md %}
+
+
 ## See also
 
 ### Tasks