وضعیت
یک تیم پلتفرم پادهای (Pod) SGLang را با بهروزرسانی تدریجی (Rolling Update) مستقر میکند. کانتینر، سرور را از طریق یک اسکریپت رپر (Wrapper) کوچک اجرا میکند. وقتی هماهنگکننده (Orchestrator) از پاد میخواهد متوقف شود، رپر سیگنالی را که دریافت کرده به کل گروه فرایندی (Process group) خود میفرستد. در نتیجه، هر بار استقرار موجی از درخواستهای ناموفق ایجاد میکند. کاربرانی که در میانهی دریافت پاسخ بودند، با استریم قطعشده روبهرو میشوند و لاگ پادِ هر سرورِ متوقفشده کرش گزارش میکند؛ هرچند هیچ مشکلی در مدل وجود نداشته است.
مهندس نوبت پاسخگویی (آنکال) انتهای یکی از لاگها را میخواند و رد کرش را در آن میبیند. تیم دو پیشنهاد دارد: افزایش مهلت خاتمه (Grace period) از 30 ثانیه به پنج دقیقه، و افزودن تلاش مجدد (Retry) در درگاه ورودی (Gateway) برای استریمهای قطعشده. شما پیش از اعمال هرکدام از این تغییرات، شواهد را بررسی میکنید.
- نسخه
- SGLang 0.5.22 on its MLX path
- مدل
- mlx-community/Qwen3-0.6B-4bit
- سختافزار
- one laptop with unified memory, which captures no CUDA graphs
شواهد
drain-finishes.txt
title: the request completes and the server exits
source: manuals/sglang-101/capture/out/shutdown-exploratory.log
lines: 176-182
lang: text
note: The in-flight request returns 200, the remaining count reaches 0, and the server process finishes.
---
[2026-10-16 14:14:04] INFO: 127.0.0.1:53209 - "POST /generate HTTP/1.1" 200 OK
[2026-10-16 14:14:07] Gracefully exiting... Remaining number of requests 0. Remaining requests remaining_rids=[].
[2026-10-16 14:14:07] kill_process_tree called: parent_pid=53853, include_parent=False, pid=53853
[2026-10-16 14:14:07] INFO: Shutting down
[2026-10-16 14:14:07] INFO: Waiting for application shutdown.
[2026-10-16 14:14:07] INFO: Application shutdown complete.
[2026-10-16 14:14:07] INFO: Finished server process [53853]
group-signal.txt
title: the end of the default run, after a SIGTERM to the whole process group
source: manuals/sglang-101/capture/out/server-default.log
lines: 565-570
lang: text
note: The scheduler child died with exit code -15 before the parent could drain, so the parent took the crash path and killed the tree.
---
[2026-10-16 14:01:45] SIGTERM received. signum=None frame=None. Draining requests and shutting down...
[2026-10-16 14:01:45] Subprocess scheduler_0 (pid=5909) crashed with exit code -15. Triggering SIGQUIT for cleanup...
[2026-10-16 14:01:45] SIGQUIT received. signum=None, frame=None. It usually means one child failed.
[2026-10-16 14:01:46] Sleeping 5 seconds before crash diagnostics to let GPU activity settle.
[2026-10-16 14:01:51] No live scheduler processes found; skipping py-spy and CUDA coredump.
[2026-10-16 14:01:51] kill_process_tree called: parent_pid=5782, include_parent=True, pid=5782
how-the-drain-works.txt
title: what the server does on a SIGTERM to its main process
source: manuals/sglang-101/sections/7-1-operating-sglang.md
lines: 98-98
lang: text
note: Read the flag, the two timers and the order of the steps.
---
On SIGTERM, the HTTP server sets `gracefully_exit`, and `/health` starts to return 503. A watchdog in the tokenizer manager checks the flag every 5 s {{code}}. It then logs the remaining requests every 5 s until none remain. Then it sends `ShutdownReq` to the schedulers and gives them 15 s to exit before it kills them. [Figure 7.1](#fig-7-1) shows this path and the two paths that skip the drain.
main-process-signal.txt
title: SIGTERM to the main process only, with one request running
source: manuals/sglang-101/capture/out/shutdown-exploratory.log
lines: 120-127
lang: text
note: The decode batches continue after the signal, and the health check returns 503 during the drain.
---
[2026-10-16 14:13:54] SIGTERM received. signum=None frame=None. Draining requests and shutting down...
[2026-10-16 14:13:54] Decode batch, #running-req: 1, #token: 8, token usage: 0.00, cuda graph: False, gen throughput (token/s): 155.12, #queue-req: 0
[2026-10-16 14:13:54] Decode batch, #running-req: 1, #token: 8, token usage: 0.00, cuda graph: False, gen throughput (token/s): 161.61, #queue-req: 0
[2026-10-16 14:13:54] Decode batch, #running-req: 1, #token: 8, token usage: 0.00, cuda graph: False, gen throughput (token/s): 182.29, #queue-req: 0
[2026-10-16 14:13:54] Decode batch, #running-req: 1, #token: 8, token usage: 0.00, cuda graph: False, gen throughput (token/s): 204.07, #queue-req: 0
[2026-10-16 14:13:55] Decode batch, #running-req: 1, #token: 8, token usage: 0.00, cuda graph: False, gen throughput (token/s): 214.83, #queue-req: 0
[2026-10-16 14:13:55] Health check request received during shutdown. Returning 503.
[2026-10-16 14:13:55] INFO: 127.0.0.1:53237 - "GET /health HTTP/1.1" 503 Service Unavailable
two-exits-skip-the-drain.txt
title: the forced exit, the variable name trap and the grace period rule
source: manuals/sglang-101/sections/7-1-operating-sglang.md
lines: 157-161
lang: text
note: Read which variable name the watchdog reads at 0.5.22, then the rule for the grace period.
---
The code has two exits that skip the drain. If the server is already `UnHealthy`, the watchdog exits at once. It also exits at once if the environment variable `SGL_FORCE_SHUTDOWN` is true. At v0.5.22 the watchdog reads that old name directly {{code}}.
The environment module declares the new name `SGLANG_FORCE_SHUTDOWN`. Its compatibility code copies `SGL_` variables to `SGLANG_` names, never the other way. **The code shows** that setting only `SGLANG_FORCE_SHUTDOWN` does not reach the watchdog. We read this in the code and did not run it, so we call it a likely bug. If you need a forced stop, set `SGL_FORCE_SHUTDOWN=1`.
**Our position:** set the termination grace period longer than your longest request at your output cap. A 32K-token answer at 30 tokens per second needs more than 18 minutes. Cap `max_tokens` before you set the grace period, or a drain can never finish in time.
what-the-client-saw.txt
title: what the client saw across the drain
source: manuals/sglang-101/capture/out/shutdown-exploratory.txt
lang: text
note: The request for 3000 tokens finished, and the exit code was 0.
---
health before SIGTERM: 200
sent SIGTERM to the server process only
health during drain: 503
in-flight request: {"status": 200, "completion_tokens": 3000, "finish_reason": {"type": "length", "length": 3000}, "seconds": 14.2}
server exit code: 0
سؤالها
- لاگ میگوید یک زیرفرایند با کد خروج 15- کرش کرده است. این کد خروج چیست و چه کسی آن را فرستاده است؟
- شرح تخلیه (Drain) را بخوانید. کدام فرایند باید سیگنال را دریافت کند، و در حین اجرای تخلیه چه اتفاقی برای اندپوینت سلامت میافتد؟
- در تصویر دوم، در حالی که درخواستی در حال اجراست، سیگنال به یک فرایند فرستاده میشود. ردگیری محاسبات درخواست را از لحظهی سیگنال تا کد خروج دنبال کنید.
- افزایش مهلت خاتمه پیشنهاد شده بود. چه چیزی مقدار مناسب آن را تعیین میکند، و چرا سقف طول خروجی اولویت اول است؟
- دو روشی را که سرور تخلیه را دور میزند، به همراه تلهی متغیر محیطی در این نسخه نام ببرید.
اول شواهد را بخوانید و به سؤالها جواب بدهید، بعد راهحل را باز کنید.
راهحل گامبهگام
- کد خروج را تحلیل کنید. کد خروج منفی همان شمارهی سیگنال است، و 15 به SIGTERM اشاره دارد. در گزارش لاگ اول، فرایند والد ثبت میکند که SIGTERM را دریافت کرده و تخلیه را کلید میزند، و در همان ثانیه زیرفرایند اسکژولر (Scheduler) آن با همان سیگنال از کار میافتد. دو فرایند در یک لحظه سیگنال یکسانی دریافت نمیکنند، مگر اینکه فرستنده کل گروه را هدف گرفته باشد؛ کاری که رپر انجام داد. اسکژولر زودتر متوقف شد، والد با دیدن مرگ فرزند وارد مسیر کرش شد، 5 ثانیه برای ثبت اطلاعات عیبیابی درنگ کرد و کل درخت فرایند را بست. تمام درخواستهای در حال اجرا همراه با اسکژولر از دست رفتند. کرش ثبتشده در لاگ نشانهی رفتار رپر است، نه نقصی در سرور.
- بررسی کنید مدیریت تخلیه با کیست. مستندات این مسیر را شرح میدهد. با دریافت SIGTERM، سرور HTTP متغیر
gracefully_exitرا مقداردهی میکند و اندپوینت/healthپاسخ 503 برمیگرداند. ناظر (Watchdog) در بخش مدیریت توکنایزر هر 5 ثانیه این فلگ را بررسی میکند و تعداد درخواستهای باقیمانده را هر 5 ثانیه لاگ میاندازد تا زمانی که هیچ درخواستی نماند. سپس درخواستShutdownReqرا برای اسکژولرها میفرستد و 15 ثانیه به آنها فرصت خروج میدهد، پیش از آنکه آنها را متوقف کند. تخلیه در فرایند اصلی انجام میشود. اسکژولری که خودش مستقیماً سیگنال را دریافت کند، هرگز درخواست خاموشی دریافت نمیکند؛ بنابراین فرایند تخلیه اصلاً آغاز نمیشود. - توقف تمیز را بررسی کنید. در ثبت دوم، آزمون ارزیابی (Probe) سیگنال SIGTERM را تنها به فرایند سرور فرستاد، در حالی که یک درخواست 3000 توکنی در حال پردازش بود. دستههای رمزگشایی (Decode batches) بعد از سطر ثبت سیگنال ادامه پیدا میکنند، و یک ثانیه بعد لاگ نشان میدهد که یک بررسی سلامت (Health check) حین خاموشی رسیده و پاسخ 503 گرفته است. این 503 همان پاسخی است که هماهنگکننده نیاز دارد: به این سمت ترافیک نفرستید، پاد در حال جمعآوری است. ده ثانیه بعد درخواست با کد 200 به پایان میرسد، ناظر عدد صفر را برای درخواستهای باقیمانده ثبت میکند و کار فرایند سرور تمام میشود.
- بررسی کنید کلاینت چه دید. وضعیت سلامت پیش از سیگنال 200 بود و در طول تخلیه 503؛ درخواست با همهی 3000 توکن و علت اتمام
lengthپس از 14.2 ثانیه کامل شد و کد خروج 0 ثبت شد. هیچ چیزی از دست نرفت و سرور حدود سیزده ثانیه پس از سیگنال بسته شد. - دو حالتی را که تخلیه را دور میزنند بخوانید. سروری که از قبل در وضعیت
UnHealthyباشد، بلافاصله خارج میشود؛ همچنین سروری که متغیرSGL_FORCE_SHUTDOWNبرای آن تنظیم شده باشد. ماژول محیطی، نام جدیدSGLANG_FORCE_SHUTDOWNرا معرفی میکند، اما کد سازگاری آن فقط نامهای قدیمی را به نامهای جدید کپی میکند؛ بنابراین ناظر در این نسخه همچنان نام قدیمی را میخواند. تعریفِ صرف نام جدید عملاً اثری ندارد. مستندات این مورد را از روی کد خوانده، اجرا نکرده، و آن را یک باگ احتمالی میداند. همان لیست قاعدهی مهلت خاتمه را نیز مشخص میکند: باید طولانیتر از زمان پردازش یک درخواست در سقف خروجی باشد؛ تولید یک پاسخ 32K توکنی با نرخ 30 توکن در ثانیه به بیش از 18 دقیقه زمان نیاز دارد.
نتیجه
ریشهی حادثه همان اسکریپت رپر بود. رپر یک سیگنال SIGTERM را به سیگنالی برای همهی فرایندها تبدیل کرد؛ اسکژولر پیش از آنکه والد بتواند تخلیه را مدیریت کند متوقف شد و والد کرشی را گزارش داد که خودش علت آن نبود. راهحل این است که sglang serve فرایند اصلی کانتینر باشد؛ با استفاده از exec در اسکریپت یا در قالب entrypoint، تا سیگنال هماهنگکننده تنها به خود سرور برسد. این شواهدْ اثبات ماجراست: با ارسال سیگنال فقط به یک فرایند، درخواست 3000 توکنی کامل شد، /health در طول تخلیه 503 برگرداند و کد خروج 0 شد.
سپس زمان توقف را مشخص کنید. ابتدا برای max_tokens سقف بگذارید و مهلت خاتمه را بیشتر از مدتزمان یک درخواست در آن سقف تعیین کنید. مهلت پنج دقیقهای بدون سقف خروجی، باز هم هر پاسخی را که بیش از پنج دقیقه طول بکشد قطع میکند. برای توقف اجباری در محیط تست، SGL_FORCE_SHUTDOWN=1 را تنظیم کنید، نه فقط نام جدید را. نیازی به افزودن تلاش مجدد در درگاه ورودی نیست: تخلیهْ پاسخ را روی همان پادی که کش را نگه داشته تمام میکند، اما تلاش مجدد پاسخ را از توکن اول روی پادی دیگر از نو میسازد.
مسیرهای اشتباه رایج
- «مهلت خاتمه را به پنج دقیقه افزایش دهید.» سیگنال مستقیماً به زیرفرایند اسکژولر رسید، بنابراین تخلیه اصلاً شروع نشد. هیچ مهلتی به تخلیهای که شروع نشده کمکی نمیکند، و مهلتی کمتر از زمان یک پاسخ در سقف خروجی هم همچنان پاسخها را قطع میکند.
- «استریمهای قطعشده را در درگاه ورودی دوباره امتحان کنید.» تلاش مجدد، هزینهی پردازش پرامپت و توکنهای تولیدشده را بار دیگر روی پادی دیگر تحمیل میکند. فرایند تخلیه پاسخ را در همانجایی که در حال اجراست به پایان میرساند.
- «متغیر SGLANG_FORCE_SHUTDOWN=1 را برای توقف سریع در استیجینگ تنظیم کنید.» در این نسخه ناظر متغیر SGL_FORCE_SHUTDOWN را میخواند؛ بنابراین نام جدید کاری از پیش نمیبرد. از طرفی توقف اجباری فرایند تخلیه را دور میزند که خودْ اصل حادثه بود.
- «اسکژولر کرش کرد، پس برای موتور گزارش باگ ثبت کنید.» کد خروج 15- سیگنال است، نه نقص فنی. لاگ به وضوح نشان میدهد چه کسی اول خاموش شد و چه کسی سیگنال را فرستاد.
درس کلی
توقف تدریجی پروتکلی میان یک فرستنده و یک گیرنده است. مشخص کنید کدام فرایند تخلیه را در دست دارد، مطمئن شوید فقط همان فرایند سیگنال را دریافت میکند، و زمانی را که به آن میدهید بر اساس طولانیترین پردازشی که مجاز دانستهاید تنظیم کنید. سپس فرایند توقف را در حین اجرای یک درخواست در حال پردازش بیازمایید و کد خروج را بررسی کنید؛ توقفی که روی سرور بیبار کار کند، چیزی را اثبات نمیکند.
کجای دوره آموزش داده میشود
راهنمای SGLang هر دو حالت توقف و تلهی نام متغیر را در بخش خاموشی در صفحهی عملیات ثبت کرده است، و درس مهندسی قابلیت اطمینان برای هوش مصنوعی (SRE for AI) ساختار رانبوکی را ارائه میدهد که این بررسی را به یک آزمون تکرارپذیر تبدیل میکند.