بخش 5.2 · اندازه‌گیری عملکرد سرور

اندپوینت /metrics

The /metrics endpoint

فهرست مطالب
  1. ابتدا آن را فعال کنید
  2. سه نوع سری زمانی
  3. دو روش برای محاسبه‌ی نرخ اصابت کش
  4. روی چه مواردی هشدار بگذاریم
  5. موضع ما
  6. حوادث

گیج‌ها وضعیت یک لحظه را گزارش می‌کنند و گیجِ نرخ اصابت کش هم فقط یک بازه‌ی ثبت لاگ را نشان می‌دهد؛ بنابراین باید برای هشدارها، روی شمارنده‌ها و هیستوگرام‌ها در یک بازه‌ی زمانی تکیه کنید.

داشبورد شما نشان می‌دهد که نرخ اصابت (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) زیر پس از تمام آزمایش‌های پیش‌فرض و در زمان بیکاری سرور ثبت شده است.

گیج‌ها در حالت بیکار capture/out/metrics.txt
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 هستند.

پنج گیج، وضعیت بیکار سرور را نشان می‌دهند، اما یکی از آن‌ها نه. نرخ اصابت کش هنوز مقدار آخرین دسته‌ی پیش‌پرکنیِ اجراشده را نگه داشته است که مربوط به بنچمارک پیشوند مشترک بود. گیج به این پرسش پاسخ می‌دهد که «در آخرین بازه چه اتفاقی افتاد»، و وقتی هیچ اتفاقی نمی‌افتد، برخی گیج‌ها به صفر میل می‌کنند و برخی دیگر آخرین مقدار خود را نگه می‌دارند.

دو روش برای محاسبه‌ی نرخ اصابت کش

اسکژولر این گیج را بر اساس توکن‌های پیش‌پرکنیِ یک بازه‌ی ثبت لاگ محاسبه می‌کند. این مقدار از تقسیم توکن‌های اصابت‌کرده بر مجموع توکن‌های اصابت‌کرده به اضافه‌ی توکن‌های محاسبه‌شده به دست می‌آید. شمارنده‌های زیر همین دو مقدار را از زمان روشن شدن سرور جمع می‌زنند.

شمارنده‌های پشت نرخ اصابت capture/out/metrics.txt
# 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 را نشان می‌دهد. هر دو عدد درست‌اند، ولی به دو پرسش متفاوت پاسخ می‌دهند. گیج وضعیت بنچمارک پیشوند مشترک را در پایان اجرا توصیف می‌کند. شمارنده‌ها کل آن اجرا را توصیف می‌کنند؛ از جمله بنچمارک‌های با پرامپت تصادفی را که هیچ اصابتی در کش نداشتند.

یک سرور، دو نرخ اصابت کشگیج مقدار بازه پیش‌پرکنی آخر را 0.942 گزارش کرد، در حالی که شمارنده‌ها در کل اجرا 0.636 را نشان دادند.
یک سرور، دو نرخ اصابت کش سمت چپ، گیج cache_hit_rate که در هر بازه لاگ بازنویسی می‌شود، برای آخرین بازه پیش‌پرکنی مقدار 0.942 را نشان می‌دهد. سمت راست، شمارنده device_hit با 182,079 توکن و شمارنده input با 104,057 توکن، نسبت 182,079 تقسیم بر 286,136 را می‌دهند که در کل اجرا برابر با 0.636 است. A · گیج B · شمارنده‌ها sglang:cache_hit_rate گیج، بازنویسی در هر بازه لاگ 0.942 فقط آخرین بازه پیش‌پرکنی device_hit 182,079 توکن input 104,057 توکن 182,079 / 286,136 = 0.636 کل پیش‌پرکنی از زمان شروع سرور
سمت چپ، گیج و بازه‌ای که به خاطر دارد. سمت راست، دو شمارنده و نسبت آن‌ها. سبز توکن‌های کش‌شده و آلبالویی توکن‌های پیش‌پرکنی محاسبه‌شده است. برگرفته از capture/out/metrics.txt پس از آزمایش‌های پیش‌فرض.

متن راهنمای این شمارنده، فرمول محاسبه‌ی نرخ در یک بازه‌ی زمانی را ارائه می‌دهد. این فرمول در 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 مربوط به همان درخواست‌های مشخص را با هم مقایسه کنید.

زمان صف در برابر زمان توکن اول capture/out/metrics.txt
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.

ترجمه‌ی فارسی The /metrics endpoint از راهنمای SGLang 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما