doc: Notes about worker keepalive support

docs/source/design.rst

@@ -34,6 +34,10 @@ as any errors will affect at most a single request. Though as we describe below
 only processing a single request at a time requires some assumptions about how
 applications are programmed.
 
+``sync`` worker does not support persistent connections - each connection is
+closed after response has been sent (even if you manually add ``Keep-Alive``
+or ``Connection: keep-alive`` header in your application).
+
 Async Workers
 -------------
 

docs/source/settings.rst

@@ -234,7 +234,14 @@ keepalive
 
 The number of seconds to wait for requests on a Keep-Alive connection.
 
-Generally set in the 1-5 seconds range.
+Generally set in the 1-5 seconds range for servers with direct connection
+to the client (e.g. when you don't have separate load balancer). When
+Gunicorn is deployed behind a load balancer, it often makes sense to
+set this to a higher value.
+
+.. note::
+   ``sync`` worker does not support persistent connections and will
+   ignore this option.
 
 Security
 --------

gunicorn/config.py

@@ -760,7 +760,14 @@ class Keepalive(Setting):
     desc = """\
         The number of seconds to wait for requests on a Keep-Alive connection.
 
-        Generally set in the 1-5 seconds range.
+        Generally set in the 1-5 seconds range for servers with direct connection
+        to the client (e.g. when you don't have separate load balancer). When
+        Gunicorn is deployed behind a load balancer, it often makes sense to
+        set this to a higher value.
+
+        .. note::
+           ``sync`` worker does not support persistent connections and will
+           ignore this option.
         """