گیجها وضعیت یک لحظه را گزارش میکنند و گیجِ نرخ اصابت کش هم فقط یک بازهی ثبت لاگ را نشان میدهد؛ بنابراین باید برای هشدارها، روی شمارندهها و هیستوگرامها در یک بازهی زمانی تکیه کنید.
داشبورد شما نشان میدهد که نرخ اصابت (hit rate) کش پیشوند 94 درصد است. در همان اجرا، سرور 104,057 توکن پرامپت را محاسبه کرده و 182,079 توکن را از کش خوانده است؛ یعنی نرخ اصابت واقعی 64 درصد بوده است. هر دو عدد از یک بار خواندن متریکها (scrape) از سرور در دادههای ضبطشدهی ما به دست آمدهاند. یکی از آنها یک گیج (gauge) است که آخرین دستهی پیشپرکنی (prefill) ثبتشده در لاگ را به خاطر دارد. دیگری یک جفت شمارنده (counter) است که همهچیز را از ابتدا ثبت میکند.
پس از پایان این بخش، میتوانید این اندپوینت را فعال کنید، تفاوت بین گیج، شمارنده و هیستوگرام را تشخیص دهید، یک نرخ اصابت معنادار محاسبه کنید و شش هشدار برای سروری بنویسید که از زانوی منحنی ظرفیتش گذشته است.
ابتدا آن را فعال کنید
این اندپوینت بهطور پیشفرض غیرفعال است. فیلد enable_metrics در نسخهی v0.5.22 بهطور پیشفرض روی False تنظیم شده است {{code}}، و بدون آرگومان --enable-metrics سرور اصلاً مسیر /metrics را مانت نمیکند. سرورِ ثبت دادههای ما با همین پرچم اجرا شد، همانطور که در بخش 5.1 آمده است. پس از اجرای آزمایشهای پیشفرض، این سرور 81 خانوادهی متریک را در قالب 603 خط نمونه صادر کرد که با :sglang شروع میشوند.
موضع ما: همهی سرورها را با --enable-metrics بالا بیاورید، حتی سروری که روی لپتاپتان اجرا میکنید. ما هزینهی سربار آن را اندازه نگرفتیم، اما انتظار داریم در مقایسه با یک گام رمزگشایی (decode) بسیار ناچیز باشد. هزینهی رخ دادن یک حادثه بدون ثبت تاریخچهی متریکها، هدر رفتن کل زمان عیبیابی شماست.
سه نوع سری زمانی
گیج (gauge): مقداری است که اسکژولر (scheduler) در هر بازهی ثبت لاگ، آن را بازنویسی میکند؛ مثل تعداد درخواستهای در حال اجرا. در هر بار خواندن متریکها فقط آخرین مقدار دیده میشود. شمارنده (counter): مقداری افزایشی است که فقط بالا میرود؛ مثل تعداد توکنهای پرامپتِ پردازششده. این مقدار را با محاسبهی نرخ در یک بازهی زمانی میخوانید. هیستوگرام (histogram): مجموعهای از شمارندههاست (یکی به ازای هر باکت یا bucket) که تعداد درخواستهای زیر هر حد مشخص را میشمارد. صدکها را با محاسبهی نرخ آن روی یک بازهی زمانی استخراج میکنید.
اسنپشات (snapshot) زیر پس از تمام آزمایشهای پیشفرض و در زمان بیکاری سرور ثبت شده است.
sglang:num_running_reqs{…} 0.0
sglang:num_queue_reqs{…} 0.0
sglang:gen_throughput{…} 0.0
sglang:token_usage{…} 0.0
sglang:cache_hit_rate{…} 0.9418739997090062
sglang:num_retracted_reqs{…} 0.0لیبلها کوتاه شدهاند. خطوط کامل شامل لیبلهای engine_type، model_name و rank هستند.
پنج گیج، وضعیت بیکار سرور را نشان میدهند، اما یکی از آنها نه. نرخ اصابت کش هنوز مقدار آخرین دستهی پیشپرکنیِ اجراشده را نگه داشته است که مربوط به بنچمارک پیشوند مشترک بود. گیج به این پرسش پاسخ میدهد که «در آخرین بازه چه اتفاقی افتاد»، و وقتی هیچ اتفاقی نمیافتد، برخی گیجها به صفر میل میکنند و برخی دیگر آخرین مقدار خود را نگه میدارند.
دو روش برای محاسبهی نرخ اصابت کش
اسکژولر این گیج را بر اساس توکنهای پیشپرکنیِ یک بازهی ثبت لاگ محاسبه میکند. این مقدار از تقسیم توکنهای اصابتکرده بر مجموع توکنهای اصابتکرده به اضافهی توکنهای محاسبهشده به دست میآید. شمارندههای زیر همین دو مقدار را از زمان روشن شدن سرور جمع میزنند.
# HELP sglang:prefill_effective_tokens_total Effective prefill tokens with retracted-request re-counts excluded, updated on each log interval. mode: device_hit, host_hit, storage_hit, input. Windowed prefix cache hit rate = rate(sum of *_hit) / rate(sum of all modes); per-tier rate uses a single *_hit mode in the numerator.
sglang:prefill_effective_tokens_total{…mode="input"…} 104057.0
sglang:prefill_effective_tokens_total{…mode="device_hit"…} 182079.0
sglang:prefill_effective_tokens_total{…mode="host_hit"…} 0.0
sglang:prefill_effective_tokens_total{…mode="storage_hit"…} 0.0لیبلها به جز mode کوتاه شدهاند. خط HELP بهطور کامل نشان داده شده است.
متن راهنما (HELP) میگوید توکنهای بازشماریشده در این مقدار محاسبه نمیشوند. در کد، این موضوع فقط برای حالت input صدق میکند. سه حالتِ دیگرِ اصابت، تعداد خام اصابتها را جمع میزنند؛ بنابراین پس از یک پسزدگی (retraction)، ممکن است همان توکنها را دو بار بشمارند {{code}}. اجرای ما هیچ پسزدگیای نداشت، بنابراین اعداد زیر دقیق هستند.
بر اساس شمارندهها، نرخ اصابت برای کل زمان اجرا برابر است با 182,079 تقسیم بر 286,136 که میشود 0.636. اما گیج عدد 0.942 را نشان میدهد. هر دو عدد درستاند، ولی به دو پرسش متفاوت پاسخ میدهند. گیج وضعیت بنچمارک پیشوند مشترک را در پایان اجرا توصیف میکند. شمارندهها کل آن اجرا را توصیف میکنند؛ از جمله بنچمارکهای با پرامپت تصادفی را که هیچ اصابتی در کش نداشتند.
متن راهنمای این شمارنده، فرمول محاسبهی نرخ در یک بازهی زمانی را ارائه میدهد. این فرمول در PromQL به این شکل نوشته میشود:
sum(rate(sglang:prefill_effective_tokens_total{mode=~".*_hit"}[5m]))
/ sum(rate(sglang:prefill_effective_tokens_total[5m]))
سروری که با --disable-radix-cache اجرا شد، در اسنپشات خود مقدار 0.0 را برای گیج گزارش کرد؛ بنابراین گیج در شرایطی که هیچ اصابتی رخ ندهد به صفر میرسد. مقدار پایینِ شمارندهها همان سیگنالی است که بخش 3.4 به شما یاد میدهد چطور بر اساس آن دستبهکار شوید.
روی چه مواردی هشدار بگذاریم
این شش سری زمانی، خرابیهای مطرحشده در این راهنما را پوشش میدهند. تمام نامهای زیر در دادههای ضبطشدهی ما وجود دارند.
| سری زمانی | نوع | زمان فعالسازی هشدار | دلیل |
|---|---|---|---|
time_to_first_token_seconds |
histogram | صدک 99 در بازهی 5 دقیقهای بالاتر از هدف شما باشد | کاربران قبل از هر چیز منتظر اولین توکن میمانند |
inter_token_latency_seconds |
histogram | صدک 99 در بازهی 5 دقیقهای بالاتر از هدف شما باشد | دستههای پیشپرکنی مانع از ادامهی رمزگشاییهای در حال اجرا میشوند؛ همانطور که فاصلهی 1,948 میلیثانیهای در بخش 5.1 نشان داد |
num_queue_reqs |
gauge | برای چند دقیقه بالاتر از 0 بماند | سرور از زانوی ظرفیت خود گذشته است و درخواستهای جدید فقط معطل میشوند |
token_usage |
gauge | برای چند دقیقه نزدیک به 1.0 بماند | استخر KV پر شده و مرحلهی بعدی پسزدگی است |
num_retracted_requests_total |
counter | نرخ رشد بالاتر از حدود 1 در دقیقه باشد | اسکژولر درخواستها را پس زده و دوباره آنها را محاسبه میکند؛ به بخش 2.3 مراجعه کنید |
prefill_effective_tokens_total |
counter | افت نرخ اصابت در بازهی زمانی مشخص پس از استقرار نسخهی جدید | تغییر پرامپت باعث شکسته شدن پیشوند شده است؛ به بخش 3.4 مراجعه کنید |
صدک 99 یک هیستوگرام از باکتهای آن به دست میآید:
histogram_quantile(0.99,
sum by (le) (rate(sglang:time_to_first_token_seconds_bucket[5m])))
ما هر دو هیستوگرام را در یک اسنپشات اندازه گرفتیم. هیستوگرام زمان صف مجموع 251.7 ثانیه را برای 266 درخواست نشان میدهد؛ یعنی میانگین 0.95 ثانیه. هیستوگرام TTFT در حالت استریمینگ (streaming)، مجموع 612.7 ثانیه را برای 261 درخواست ثبت کرده است؛ یعنی میانگین 2.35 ثانیه. این دو سری، درخواستهای متفاوتی را میشمارند؛ بنابراین نسبت آنها یک تخمین است، نه سهمِ دقیق و اندازهگیریشده. این اعداد نشان میدهند که در این Mac، زمان صف بخش بزرگی از زمان رسیدن به اولین توکن بوده است. برای به دست آوردن سهم دقیق، زمان صف و TTFT مربوط به همان درخواستهای مشخص را با هم مقایسه کنید.
sglang:queue_time_seconds_sum{…} 251.74525608913973
sglang:queue_time_seconds_count{…} 266.0
sglang:time_to_first_token_seconds_sum{…is_streaming="true"…} 612.7282021734864
sglang:time_to_first_token_seconds_count{…is_streaming="true"…} 261.0لیبلها به جز is_streaming کوتاه شدهاند.
موضع ما
برای تاخیر (latency) و فعالیت (activity)، بر اساس صدکهای هیستوگرام و نرخ تغییرات شمارنده در یک بازهی زمانی هشدار بگذارید. برای وضعیت، فقط زمانی از گیج استفاده کنید که آن شرایط پایدار بماند؛ مانند ماندن num_queue_reqs بالای 0 یا نزدیک بودن token_usage به 1.0 برای چندین دقیقه. یک بار خواندن مقدار گیج، فقط چند ثانیهی گذشته را توصیف میکند. هرگاه بین گیج و شمارنده اختلافی دیدید (مانند آنچه در نرخ اصابت کش رخ داد)، باید به شمارنده اعتماد کنید.
پیش از آنکه سامانهی خود را بر پایهی هر متریک جدیدی بسازید، متن HELP و کد آن را بخوانید. همهی گیجها به درستی کار نمیکنند.
حوادث
گیجی که هرگز تکان نمیخورد. در کد اسکژولر نسخهی v0.5.22 کامنتی وجود دارد مبنی بر اینکه متریک sglang:utilization به دلیل یک پسرفت (regression) متصل به #22713 روی عدد 0 باقی مانده است {{code}}. دادههای ضبطشدهی ما نیز این را تأیید میکنند: مقدار این گیج پس از اجرایی که سرور را چند دقیقه مشغول نگه داشت، همچنان 0.0 بود. اگر در داشبورد خود قاب (pane) یا پنلی بر اساس آن میساختید، در جریان یک قطعی کامل هم کل ناوگان را بیکار نشان میداد.
آزمون سلامتی که کارها را روی هم انباشت. بر اساس گزارش خطا #35884، فراخوانی با اتمام مهلت زمانی (timeout) در /health، درخواست مربوط به آن را در اسکژولر لغو نمیکرد {{issue #35884}}. هر آزمون ارزیابیِ (probe) ناموفق، یک درخواست رهاشدهی دیگر در سیستم باقی میگذاشت و زیر بار سنگین، خودِ این پروبها به باری اضافه میشدند که قرار بود وجودش را شناسایی کنند. گزارش دیگری در همین زمینه در گزارش خطا #22511 نشان میدهد که زیر بار کاری سنگین روی یک مدل بزرگ، پیام «health check failed» رخ میدهد {{issue #22511}}. سریهای زمانیِ صف و تاخیر را زیر نظر بگیرید و آزمون ارزیابی ناموفق را فقط نشانهای در کنار سایر علائم خرابی در نظر بگیرید.
منابع: python/sglang/srt/arg_groups/fields/observability.py (برای enable_metrics)، python/sglang/srt/managers/scheduler_components/metrics_reporter.py (برای نرخ اصابت کش و utilization)، python/sglang/srt/observability/metrics_collector.py، همگی در نسخهی v0.5.22 (با هش baa9befa)؛ فایلهای capture/out/metrics.txt، capture/out/no-radix-cache-metrics.txt، capture/out/server-default.command.txt؛ و ایشوهای #35884 و #22511.