From db212bdc129e2c6ae2b72f25736a480e940e9b01 Mon Sep 17 00:00:00 2001 From: Tanmoy Sarkar Date: Fri, 12 Jun 2026 23:57:24 +0530 Subject: [PATCH] docs: Regenerate settings.rst for companion settings The docs CI builds Sphinx, which regenerates settings.rst from the Setting classes in config.py and fails if the working tree changes. The new Companion Processes settings were missing from the committed file. Regenerate it (also picks up a stale grp.getgrnam line). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/source/settings.rst | 238 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 237 insertions(+), 1 deletion(-) diff --git a/docs/source/settings.rst b/docs/source/settings.rst index e1e91fa7..330ae7d9 100644 --- a/docs/source/settings.rst +++ b/docs/source/settings.rst @@ -20,6 +20,192 @@ for reference on setting at the command line. .. versionadded:: 19.7 +Companion Processes +------------------- + +.. _companion-config-file: + +``companion_config_file`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Command line:** ``--companion-config`` + +**Default:** ``None`` + +Dedicated Python file the manager reads for companion specs. + +Lets companions reload independently of the main Gunicorn config. +Example: ``companion_config_file = "/home/frappe/bench/companion.conf.py"``. +If unset, specs are read from the main Gunicorn config. + +.. _companion-workers: + +``companion_workers`` +~~~~~~~~~~~~~~~~~~~~~ + +**Default:** ``[]`` + +List of companion process specs, each a dict. + +A spec requires ``name`` and ``target``; other keys override defaults. +Example: ``[{"name": "scheduler", "target": "app:run_scheduler"}]``. + +.. _companion-control-socket: + +``companion_control_socket`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Command line:** ``--companion-control-socket`` + +**Default:** ``None`` + +Unix socket the manager listens on for control commands. + +Clients send ``status``/``start``/``stop``/``restart``/``reread`` as JSON. +Example: ``companion_control_socket = "/run/gunicorn/companion.sock"``. + +.. _companion-control-socket-mode: + +``companion_control_socket_mode`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Default:** ``384`` + +Octal file mode set on the control socket after it is created. + +Default ``0o600`` lets only the owner connect. +Example: ``companion_control_socket_mode = 0o660``. + +.. _companion-stop-signal: + +``companion_stop_signal`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Default:** ``'SIGTERM'`` + +Signal sent first when stopping a companion. + +The companion should catch it to drain work before exiting. +Example: ``companion_stop_signal = "SIGINT"``. + +.. _companion-stop-timeout: + +``companion_stop_timeout`` +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Default:** ``60`` + +Seconds to wait after the stop signal before sending SIGKILL. + +Give slow-draining workers a larger value. +Example: ``companion_stop_timeout = 300``. + +.. _companion-reload-timeout: + +``companion_reload_timeout`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Default:** ``60`` + +Seconds to wait for the old child to exit during restart/reread. + +Used instead of ``stop_timeout`` when replacing a companion. +Example: ``companion_reload_timeout = 30``. + +.. _companion-stdout: + +``companion_stdout`` +~~~~~~~~~~~~~~~~~~~~ + +**Default:** ``None`` + +Where to send companion stdout: a file path or ``"inherit"``. + +Files are opened in append mode; ``None`` inherits the manager's stdout. +Example: ``companion_stdout = "/var/log/frappe/rq.log"``. + +.. _companion-stderr: + +``companion_stderr`` +~~~~~~~~~~~~~~~~~~~~ + +**Default:** ``None`` + +Where to send companion stderr: a path, ``"stdout"``, or ``"inherit"``. + +Use ``"stdout"`` to merge stderr into the stdout target. +Example: ``companion_stderr = "stdout"``. + +.. _companion-cwd: + +``companion_cwd`` +~~~~~~~~~~~~~~~~~ + +**Default:** ``None`` + +Directory the child changes into before running the target. + +Example: ``companion_cwd = "/home/frappe/frappe-bench"``. + +.. _companion-env: + +``companion_env`` +~~~~~~~~~~~~~~~~~ + +**Default:** ``{}`` + +Extra environment variables merged into the child environment. + +Example: ``companion_env = {"QUEUE": "default"}``. + +.. _companion-startsecs: + +``companion_startsecs`` +~~~~~~~~~~~~~~~~~~~~~~~ + +**Default:** ``1`` + +Seconds a freshly forked companion must survive to reach RUNNING. + +Exiting earlier counts as a failed start and triggers BACKOFF. +Example: ``companion_startsecs = 5``. + +.. _companion-restart-delay: + +``companion_restart_delay`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Default:** ``5`` + +Fixed seconds to wait before restarting a crashed companion. + +No exponential backoff; the same delay is used every time. +Example: ``companion_restart_delay = 10``. + +.. _companion-manager-shutdown-buffer: + +``companion_manager_shutdown_buffer`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Default:** ``10`` + +Extra seconds added to the slowest companion timeout for the manager. + +Gives the manager headroom to stop all children before Gunicorn kills it. +Example: ``companion_manager_shutdown_buffer = 15``. + +.. _companion-manager-stop-timeout: + +``companion_manager_stop_timeout`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Default:** ``None`` + +Seconds Gunicorn waits for the manager to stop during shutdown. + +By default it uses the slowest companion ``stop_timeout`` plus a buffer. +Example: ``companion_manager_stop_timeout = 120``. + Config File ----------- @@ -1148,7 +1334,7 @@ change the worker process user. Switch worker process to run as this group. A valid group id (as an integer) or the name of a user that can be -retrieved with a call to ``pwd.getgrnam(value)`` or ``None`` to not +retrieved with a call to ``grp.getgrnam(value)`` or ``None`` to not change the worker processes group. .. _umask: @@ -1703,6 +1889,56 @@ The maximum number of simultaneous clients. This setting only affects the ``gthread``, ``eventlet`` and ``gevent`` worker types. +.. _enable-adaptive-queueing: + +``enable_adaptive_queueing`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Command line:** ``--enable-adaptive-queueing`` + +**Default:** ``False`` + +Enable adaptive multi-queue routing in the ``gthread`` worker. + +Can also be enabled by setting the ``GUNICORN_ENABLE_ADAPTIVE_QUEUEING`` +environment variable to ``true``. + +When enabled, the worker splits its :ref:`threads` roughly evenly into +two lanes — a *fast* lane and a *slow* lane — and routes each request +to one of them by predicting, from previously observed timings of the +same route (method + path), whether it will exceed +:ref:`slow-request-threshold`. Slow-predicted requests go to the slow +lane so they can never starve the fast lane, even under a flood of +slow requests. + +Requires :ref:`threads` to be at least 2. + +This setting only affects the ``gthread`` worker type. + +.. versionadded:: 23.1.0 + +.. _slow-request-threshold: + +``slow_request_threshold`` +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Command line:** ``--slow-request-threshold FLOAT`` + +**Default:** ``5.0`` + +Processing time (in seconds) above which a request route is treated as +"slow" by the ``gthread`` worker when :ref:`enable-adaptive-queueing` +is enabled. + +A route is learned as slow once it has been observed exceeding this +threshold (either on completion or while still running); its timing +decays back below the threshold if it becomes fast again. + +Only used by the ``gthread`` worker when :ref:`enable-adaptive-queueing` +is enabled. + +.. versionadded:: 23.1.0 + .. _max-requests: ``max_requests``