diff --git a/doc/htdocs/design.html b/doc/htdocs/design.html index 0ae1a4a3..36b0e543 100644 --- a/doc/htdocs/design.html +++ b/doc/htdocs/design.html @@ -104,14 +104,17 @@ the servers. For the curious,

How Many Workers?

+

DO NOT scale the number of workers to the number of clients you expect to have. +Gunicorn should only need 4-12 worker processes to handle hundreds or thousands +of requests per second.

Gunicorn relies on the operating system to provide all of the load balancing when handling requests. Generally we recommend (2 x $num_cores) + 1 as the number of workers to start off with. While not overly scientific, the formula is based on the assumption that for a given core, one worker will be reading or writing from the socket while the other worker is processing a request.

-

Obviously, your particular hardware and application are going to affect what -the optimal number of workers is. Our recommendation is to start with the above -guess and tune using TTIN and TTOU signals while the application is under load.

+

Obviously, your particular hardware and application are going to affect the +optimal number of workers. Our recommendation is to start with the above guess +and tune using TTIN and TTOU signals while the application is under load.

Always remember, there is such a thing as too many workers. After a point your worker processes will start thrashing system resources decreasing the throughput of the entire system.

diff --git a/doc/htdocs/faq.html b/doc/htdocs/faq.html index 9c207de1..3903f077 100644 --- a/doc/htdocs/faq.html +++ b/doc/htdocs/faq.html @@ -47,6 +47,11 @@
  • How can I change the number of workers dynamically?
    • +
  • Kernel Parameters +
    • @@ -108,6 +113,34 @@ $ kill -TTOU $masterpid
    +
    +

    Kernel Parameters

    +

    When dealing with large numbers of concurrent connections there are a handful of +kernel parameters that you might need to adjust. Generally these should only +affect sites with a very large concurrent load. These parameters are not +specific to Gunicorn, they would apply to any sort of network server you may be +running.

    +

    These commands are for Linux. Your particular OS may have slightly different +parameters.

    +
    +

    How can I increase the maximum number of file descriptors?

    +

    One of the first settings that usually needs to be bumped is the maximum number +of open file descriptors for a given process. For the confused out there, +remember that Unices treat sockets as files.

    +
    +$ sudo ulimit -n 2048
+
    +
    +
    +

    How can I increase the maximum socket backlog?

    +

    Listening sockets have an associated queue of incoming connections that are +waiting to be accepted. If you happen to have a stampede of clients that fill up +this queue new connections will eventually start getting dropped.

    +
    +$ sudo sysctl -w net.core.somaxconn="2048"
+
    +
    +
    diff --git a/doc/site/design.rst b/doc/site/design.rst index 8d93cd18..de157147 100644 --- a/doc/site/design.rst +++ b/doc/site/design.rst @@ -74,15 +74,19 @@ Some examples of behavior requiring asynchronous workers: How Many Workers? ================= +DO NOT scale the number of workers to the number of clients you expect to have. +Gunicorn should only need 4-12 worker processes to handle hundreds or thousands +of requests per second. + Gunicorn relies on the operating system to provide all of the load balancing when handling requests. Generally we recommend ``(2 x $num_cores) + 1`` as the number of workers to start off with. While not overly scientific, the formula is based on the assumption that for a given core, one worker will be reading or writing from the socket while the other worker is processing a request. -Obviously, your particular hardware and application are going to affect what -the optimal number of workers is. Our recommendation is to start with the above -guess and tune using TTIN and TTOU signals while the application is under load. +Obviously, your particular hardware and application are going to affect the +optimal number of workers. Our recommendation is to start with the above guess +and tune using TTIN and TTOU signals while the application is under load. Always remember, there is such a thing as too many workers. After a point your worker processes will start thrashing system resources decreasing the throughput diff --git a/doc/site/faq.rst b/doc/site/faq.rst index b2c9ad70..b9c71576 100644 --- a/doc/site/faq.rst +++ b/doc/site/faq.rst @@ -78,3 +78,36 @@ How can I change the number of workers dynamically? .. _worker_class: /configure.html#worker-class .. _`number of workers`: /design.html#how-many-workers +Kernel Parameters +================= + +When dealing with large numbers of concurrent connections there are a handful of +kernel parameters that you might need to adjust. Generally these should only +affect sites with a very large concurrent load. These parameters are not +specific to Gunicorn, they would apply to any sort of network server you may be +running. + +These commands are for Linux. Your particular OS may have slightly different +parameters. + +How can I increase the maximum number of file descriptors? +---------------------------------------------------------- + +One of the first settings that usually needs to be bumped is the maximum number +of open file descriptors for a given process. For the confused out there, +remember that Unices treat sockets as files. + +:: + + $ sudo ulimit -n 2048 + +How can I increase the maximum socket backlog? +---------------------------------------------- + +Listening sockets have an associated queue of incoming connections that are +waiting to be accepted. If you happen to have a stampede of clients that fill up +this queue new connections will eventually start getting dropped. + +:: + + $ sudo sysctl -w net.core.somaxconn="2048" diff --git a/doc/site/tuning.rst b/doc/site/tuning.rst deleted file mode 100644 index 7c977030..00000000 --- a/doc/site/tuning.rst +++ /dev/null @@ -1,68 +0,0 @@ -template: doc.html -title: Tuning - -Tuning -====== - -Unicorn Configuration ---------------------- - -DO NOT scale the number of workers to the number of clients you expect to have. -Gunicorn should only need 4-12 worker processes to handle hundreds or thousands -of simultaneous clients. Remember, Gunicorn is **NOT** designed for serving slow -clients, that's the job of Nginx_. - -See Configuration_ for a more thorough description of the available parameters. - -.. _Nginx: http://www.nginx.org -.. _Configuration: configuration.html - -Kernel Parameters ------------------ - -When dealing with large numbers of concurrent connections there are a handful of -kernel parameters that you might need to adjust. Generally these should only -affect sites with a very large concurrent load. These parameters are not -specific to Gunicorn, they would apply to any sort of network server you may be -running. - -The commands listed are tested under Mac OS X 10.6. Your flavor of Unix may use -slightly different flags. Always reference the appropriate man pages if -uncertain. - -File Descriptor Limits -++++++++++++++++++++++ - -One of the first settings that usually needs to be bumped is the maximum number -of open file descriptors for a given process. For the confused out there, -remember that Unices treat sockets as files. - -:: - - $ sudo ulimit -n 2048 - -Listen Queue Size -+++++++++++++++++ - -Listening sockets have an associated queue of incoming connections that are -waiting to be accepted. If you happen to have a stampede of clients that fill up -this queue new connections will eventually start getting dropped. - -:: - - $ sudo sysctl -w kern.ipc.somaxconn="2048" - -Ephemeral Port Range -++++++++++++++++++++ - -After a socket is closed it enters the TIME_WAIT state. This can become an issue -after a prolonged burst of client activity. Eventually the ephemeral port range -is exhausted which can cause new connections to stall while they wait for a -valid port. - -This setting is generally only required on machines that are being used to test -a network server. - -:: - - $ sudo sysctl -w net.inet.ip.portrange.first="8048"