# SGLang и Prometheus: метрики очереди локального сервера

Источник: https://modelium.tech/zhurnal/sglang-metrics-prometheus/

Для мониторинга SGLang запустите сервер с `--enable-metrics` и проверьте `http://127.0.0.1:30000/metrics`: endpoint отдаёт метрики в формате Prometheus. По `sglang:num_queue_reqs`, `sglang:num_running_reqs` и гистограмме `sglang:time_to_first_token_seconds` можно отличать ожидание в очереди от обработки запроса. Но пустая очередь при одном запросе не доказывает запас производительности: повторите проверку при контролируемой нагрузке на своей модели и не открывайте /metrics в интернет.

**Документация SGLang v0.5.20, проверена 28 сентября 2026 года.** Команды ниже составлены по зафиксированному Git-коммиту `94602c9`, но Modelium не запускал сервер, GPU, модель или мониторинговый стенд. Значения метрик появляются только в вашем окружении; цифры из примеров авторов не являются результатами Modelium. [s1](#src-s1) [s2](#src-s2)

## Что именно показывает `/metrics` и когда это полезно?

SGLang отдаёт Prometheus-метрики после запуска с `--enable-metrics`; документация проверяет endpoint командой `curl http://localhost:30000/metrics`. Здесь можно наблюдать текущую очередь и выполняющиеся запросы, счётчики токенов и распределение задержек. Это контроль **сервера инференса**, а не качества ответа модели, прав на данные или отсутствия сетевого выхода. [s1](#src-s1) [s2](#src-s2)

Практический маршрут: **задача → конкретная модель и GPU → SGLang → тестовый запрос → метрики → решение об изменении нагрузки**. Если вам ещё нужен первый успешный ответ, начните с [гайда запуска SGLang](/zhurnal/sglang/); пример документации использует `qwen/qwen2.5-0.5b-instruct`, но модель и её весовые файлы здесь не скачивались и пригодность к вашему железу не измерялась. Конфигурация NVIDIA sm80+ в quickstart — условия его примера, не универсальное аппаратное требование для всех вариантов SGLang. [s3](#src-s3) [s5](#src-s5)

## Как включить сбор на существующем локальном сервере?

Нужны установленный SGLang совместимой версии, рабочий inference-сервер с выбранной моделью и право перезапустить его. Проверьте свою версию, платформу и зависимости по [установке SGLang](/zhurnal/sglang/) и официальной документации: этот материал не обещает, что произвольный GPU запустит выбранные веса. В отдельном терминале перезапустите ваш сервер, **добавив** `--enable-metrics` к привычным параметрам. Следующий пример адаптирован из quickstart для тестовой модели, а не подтверждён запуском Modelium: [s1](#src-s1) [s3](#src-s3) [s5](#src-s5)

python3 -m sglang.launch_server \  --model-path qwen/qwen2.5-0.5b-instruct \  --host 127.0.0.1 --port 30000 --enable-metrics

Параметр `--host 127.0.0.1` в **этом примере** оставляет API и `/metrics` доступными лишь с той же машины. Не копируйте в публичный контейнер вариант quickstart с `--host 0.0.0.0` без отдельной сетевой политики: `/metrics` публикуется на HTTP-сервере, а не на отдельном «тайном» порту. Если Prometheus находится на другой машине, понадобится контролируемый путь доступа; не открывайте порт всем адресам ради диагностики. [s1](#src-s1) [s3](#src-s3) [s6](#src-s6)

После сообщения сервера о готовности сначала проверьте endpoint **на той же машине**: [s1](#src-s1) [s3](#src-s3)

curl -fsS http://127.0.0.1:30000/metrics | \  grep -E '^sglang:(num_queue_reqs|num_running_reqs|time_to_first_token_seconds)' | \  head -20

Ненулевой HTTP-ответ или наличие строк говорит только о работающей выдаче метрик, не о готовности к вашей нагрузке. Не принимайте числа из [образца экспорта в документации](https://github.com/sgl-project/sglang/blob/94602c9c2b7cbdb8efd5c52802dac6a1c180089e/docs/docs/references/production_metrics.mdx) за замер собственной системы. [s1](#src-s1) [s2](#src-s2)

## Как проверить метрики одним контролируемым запросом?

Отправьте запрос к уже поднятой модели через документированный `/v1/chat/completions`; имя модели в JSON должно соответствовать фактическому запуску. Это тест синтаксиса и наблюдения, **не** прогноз скорости. Используйте вымышленный текст вместо клиентских данных. [s3](#src-s3) [s4](#src-s4)

curl -fsS http://127.0.0.1:30000/v1/chat/completions \  -H 'Content-Type: application/json' \  -d '{"model":"qwen/qwen2.5-0.5b-instruct","messages":[{"role":"user","content":"Ответь одним словом: готово"}],"max_tokens":16}'curl -fsS http://127.0.0.1:30000/metrics | \  grep -E '^sglang:(num_queue_reqs|num_running_reqs|time_to_first_token_seconds_(count|sum)|generation_tokens_total)'

Проверяйте успешный HTTP-ответ и JSON с ответом, затем сравнивайте счётчики и гистограммы **до и после** запроса. `num_queue_reqs` и `num_running_reqs` — моментальные gauges: при одиночном запросе выборка после завершения может снова показать ноль. Если хотите увидеть очередь, нужен **контролируемый параллельный** тест в отдельной среде, где вы знаете пределы GPU и влияние на других пользователей; не создавайте искусственный пик на рабочем сервере. Отсутствие очереди не доказывает, что задержка под будущей нагрузкой сохранится. [s2](#src-s2) [s3](#src-s3)

## Какие серии читать в Prometheus?

- `sglang:num_queue_reqs` — запросы, ожидающие обслуживания; `sglang:num_running_reqs` — текущие запросы в работе. Сопоставляйте обе серии с потоком запросов во времени, а не с единственным снимком. [s2](#src-s2)

- `sglang:time_to_first_token_seconds` — histogram времени до первого токена (TTFT); `sglang:e2e_request_latency_seconds` — полная задержка запроса. Сравнивайте одну и ту же модель/маршрут и одинаковый тип нагрузки. `_sum` и `_count` являются составными частями гистограммы: отношение их скоростей изменения за одинаковый интервал показывает **среднее по наблюдениям**, не p95 и не задержку одного пользователя. [s2](#src-s2)

- `sglang:prompt_tokens_total` и `sglang:generation_tokens_total` — счётчики обработанных токенов; `sglang:cache_hit_rate` — показатель попаданий в cache. Без условий запросов и режима cache сравнение «быстрее после настройки» нельзя приписывать одному флагу. [s2](#src-s2)

Не копируйте примерные значения и метки из документации в отчёт как свои. У Prometheus проверьте `Targets`: статус `UP` означает, что сбор состоялся, но не подтверждает полезность интерпретации. Для рабочего решения сохраните версию SGLang, модель/ревизию, железо, параметры запуска, интервал, параллелизм и набор тестовых запросов. [s2](#src-s2) [s6](#src-s6)

## Как подключить Prometheus, не открывая метрики наружу?

Официальный пример `examples/monitoring` использует `prometheus.yaml` с target `127.0.0.1:30000` и `docker-compose.yaml` с `network_mode: host`, то есть контейнер Prometheus разделяет сетевое пространство хоста. Только **при таком устройстве на Linux** loopback контейнера указывает на тот же сервер; у обычного bridge-контейнера `127.0.0.1` означает сам контейнер. Убедитесь, что наблюдатель действительно достигает SGLang, прежде чем доверять пустому графику. [s6](#src-s6) [s7](#src-s7) [s8](#src-s8)

scrape_configs:  - job_name: sglang    static_configs:      - targets: ['127.0.0.1:30000']

При желании используйте примерный dashboard SGLang, но сначала **пересмотрите сетевые настройки** образца: его Compose включает host network для Prometheus и Grafana и `GF_AUTH_ANONYMOUS_ENABLED=true` с viewer-доступом. Не выкладывайте этот Compose на общедоступный узел без ограничения доступа, настройки учётных записей и явного решения по сети. Prometheus и Grafana не обязательны для первого локального `curl /metrics`. [s6](#src-s6) [s8](#src-s8)

## Почему график пуст и когда остановиться?

Если `/metrics` недоступен, убедитесь, что сервер поднялся, `--enable-metrics` действительно передан **процессу сервера**, адрес/порт совпадают, а `curl` запущен из той же сетевой среды. Если сам endpoint доступен, но Prometheus показывает `DOWN`, проверьте target и namespace контейнера; если показывает `UP`, но TTFT пуст, сначала отправьте тестовый запрос и проверьте ответ API. Не путайте нулевое значение gauge после запроса с отсутствием серии и не интерпретируйте мгновенное значение как p95. [s1](#src-s1) [s2](#src-s2) [s3](#src-s3) [s7](#src-s7) [s8](#src-s8)

Не включайте `--log-requests` или дамп запросов просто ради `/metrics`: документация рассматривает журналы и request dump как отдельные функции. Они могут захватывать содержимое запросов и требуют отдельного решения о хранении данных. После испытания уберите тестовую нагрузку; чтобы отключить экспорт, перезапустите сервер без `--enable-metrics`, сохраняя рабочие параметры модели и доступа. [s1](#src-s1)

**Основной следующий шаг:** откройте [гайд запуска SGLang](/zhurnal/sglang/), поднимите подходящую модель и подтвердите ответ её API, затем соберите собственный снимок `/metrics` до и после безопасного теста. [Сравнение SGLang и vLLM](/zhurnal/sglang-ili-vllm/) поможет выбрать иной runtime, а [оценка видеопамяти](/zhurnal/videokarta-dlya-llm/) — понять аппаратные ограничения; ничто из этого не заменяет измерение на вашем сервере. [s2](#src-s2) [s3](#src-s3)

## Источники

1. [SGLang v0.5.20 — Observability](https://github.com/sgl-project/sglang/blob/94602c9c2b7cbdb8efd5c52802dac6a1c180089e/docs/docs/advanced_features/observability.mdx) — получено 2026-09-28
2. [SGLang v0.5.20 — Production Metrics](https://github.com/sgl-project/sglang/blob/94602c9c2b7cbdb8efd5c52802dac6a1c180089e/docs/docs/references/production_metrics.mdx) — получено 2026-09-28
3. [SGLang v0.5.20 — Quickstart](https://github.com/sgl-project/sglang/blob/94602c9c2b7cbdb8efd5c52802dac6a1c180089e/docs/docs/get-started/quickstart.mdx) — получено 2026-09-28
4. [SGLang v0.5.20 — OpenAI-compatible Completions API](https://github.com/sgl-project/sglang/blob/94602c9c2b7cbdb8efd5c52802dac6a1c180089e/docs/docs/basic_usage/openai_api_completions.mdx) — получено 2026-09-28
5. [SGLang v0.5.20 — Installation](https://github.com/sgl-project/sglang/blob/94602c9c2b7cbdb8efd5c52802dac6a1c180089e/docs/docs/get-started/install.mdx) — получено 2026-09-28
6. [SGLang v0.5.20 — Monitoring example README](https://github.com/sgl-project/sglang/blob/94602c9c2b7cbdb8efd5c52802dac6a1c180089e/examples/monitoring/README.md) — получено 2026-09-28
7. [SGLang v0.5.20 — Prometheus scrape configuration](https://github.com/sgl-project/sglang/blob/94602c9c2b7cbdb8efd5c52802dac6a1c180089e/examples/monitoring/prometheus.yaml) — получено 2026-09-28
8. [SGLang v0.5.20 — Monitoring Docker Compose configuration](https://github.com/sgl-project/sglang/blob/94602c9c2b7cbdb8efd5c52802dac6a1c180089e/examples/monitoring/docker-compose.yaml) — получено 2026-09-28