feat(proxy): add --timeout_worker_healthcheck flag for uvicorn worker triage

[ryan-crabbe-berri]

Summary

• Adds CLI flag --timeout_worker_healthcheck (env TIMEOUT_WORKER_HEALTHCHECK) that forwards to uvicorn's timeout_worker_healthcheck Config kwarg (added in uvicorn 0.37.0, default 5s).
• Helper introspects uvicorn.Config.__init__ and only sets the kwarg if supported; otherwise prints a yellow warning naming the installed uvicorn version. The existing uvicorn>=0.32.1,<1.0.0 floor pin is unchanged.
• Gunicorn / Hypercorn paths untouched — the uvicorn supervisor isn't running there, so the flag is a no-op there by design (called out in the help text). When run under --run_gunicorn or --run_hypercorn, the kwarg is not passed to the helper at all so the "uvicorn too old" warning never fires spuriously.

Screenshots

Test plan

• tests/test_litellm/proxy/test_proxy_cli.py::TestProxyInitializationHelpers::test_get_default_unvicorn_init_args — extended to cover the supported branch (stubs uvicorn.Config so it's stable across uvicorn version bumps in CI)
• tests/test_litellm/proxy/test_proxy_cli.py::TestProxyInitializationHelpers::test_timeout_worker_healthcheck_flag — new CLI roundtrip test mirroring test_keepalive_timeout_flag
• Existing test_keepalive_timeout_flag updated for the new helper kwarg signature (still passes)
• Ran the full tests/test_litellm/proxy/test_proxy_cli.py file locally — 26 passed
• Manually verified end-to-end on a temporary uvicorn>=0.37 install in the venv: ProxyInitializationHelpers._get_default_unvicorn_init_args(host=..., port=..., timeout_worker_healthcheck=30) returns the kwarg in the dict, and uvicorn.Config(**args) builds with cfg.timeout_worker_healthcheck == 30
• Manually verified the unsupported-uvicorn warning path on the pinned uvicorn 0.33.0: yellow warning prints, kwarg is dropped from the args dict
• Manually verified the actual uvicorn behavior with a SIGSTOP repro: with default 5s healthcheck the supervisor logged "Child process [...] died" and respawned at ~5s; with --timeout-worker-healthcheck 30 the same SIGSTOP'd worker survived 30s before being killed

[greptile-apps]

Greptile Summary

This PR adds a --timeout_worker_healthcheck CLI flag (env TIMEOUT_WORKER_HEALTHCHECK) that threads through to uvicorn's timeout_worker_healthcheck Config kwarg, with a runtime inspect.signature guard to print a version warning and skip the kwarg on older uvicorn installs. The gunicorn/hypercorn bypass via the running_uvicorn local variable correctly prevents the warning from firing on those paths.

Confidence Score: 5/5

PR is safe to merge — changes are additive, guarded by a runtime version check, and existing behaviour is unaffected.

No P0 or P1 issues found. The is False identity check is safe because both run_gunicorn and run_hypercorn are is_flag=True Click options defaulting to False, so they can only ever be True or False. The inspect.signature version probe is correct and the test's patch("uvicorn.Config", _FakeUvicornConfig) correctly intercepts the attribute access inside the function. The only gap (else-branch coverage) was already raised in a prior review thread.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/proxy_cli.py	Adds timeout_worker_healthcheck parameter to _get_default_unvicorn_init_args, a new CLI option, and a running_uvicorn guard that passes None when gunicorn/hypercorn is active — cleanly preventing spurious version warnings.
tests/test_litellm/proxy/test_proxy_cli.py	Adds a happy-path stub test for timeout_worker_healthcheck in _get_default_unvicorn_init_args and a new CLI roundtrip test; updates test_keepalive_timeout_flag with the new kwarg — the warning/else branch remains uncovered.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[run_server CLI invoked] --> B{--run_gunicorn\nor --run_hypercorn?}
    B -- Yes --> C[running_uvicorn = False\ntimeout_worker_healthcheck = None\npassed to helper]
    B -- No --> D[running_uvicorn = True\ntimeout_worker_healthcheck = value\npassed to helper]
    C --> E[_get_default_unvicorn_init_args\ntimeout_worker_healthcheck is None\nblock skipped entirely]
    D --> F{timeout_worker_healthcheck\nis not None?}
    F -- No --> G[uvicorn_args returned\nwithout the kwarg]
    F -- Yes --> H{timeout_worker_healthcheck\nin uvicorn.Config.__init__\nsignature?}
    H -- Yes\nuvicorn >= 0.37.0 --> I[uvicorn_args includes\ntimeout_worker_healthcheck]
    H -- No\nuvicorn < 0.37.0 --> J[Print yellow warning\nkwarg dropped from args]
    I --> K[uvicorn.run called\nwith timeout_worker_healthcheck]
    G --> K
    J --> K

Loading

_{Reviews (3): Last reviewed commit: "feat(proxy): add --timeout_worker_health..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 87.50000% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/proxy/proxy_cli.py	87.50%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!