Чтобы получить чистое Markdown-содержимое этой страницы, добавьте .md к этому URL. Полный индекс документации см. на https://docs.nvidia.com/dynamo/llms.txt. Полное содержимое, включая справочник API и примеры SDK, см. на https://docs.nvidia.com/dynamo/llms-full.txt.

Наблюдаемость

В этом руководстве описаны метрики, трассировка и визуализация для развертываний SGLang, работающих через Dynamo.

Метрики Prometheus

При запуске SGLang через Dynamo метрики движка SGLang автоматически передаются дальше и публикуются на эндпоинте Dynamo /metrics (порт по умолчанию 8081). Это позволяет получать и метрики движка SGLang (с префиксом sglang:), и метрики среды выполнения Dynamo (с префиксом dynamo_*) с одного эндпоинта backend-воркера.

Полный и авторитетный список всех метрик SGLang всегда смотрите в официальной документации SGLang Production Metrics.

Метрики среды выполнения Dynamo описаны в руководстве по метрикам Dynamo.

Инструкции по настройке визуализации см. в руководстве по настройке Prometheus и Grafana.

Переменные окружения

Variable	Description	Default	Example
`DYN_SYSTEM_PORT`	Порт системных метрик/проверки работоспособности	`-1` (отключено)	`8081`

Быстрый старт

Это пример для одной машины.

Запустите стек наблюдаемости

Чтобы визуализировать метрики с помощью Prometheus и Grafana, запустите стек наблюдаемости. Инструкции см. в разделе начало работы с наблюдаемостью.

Запустите компоненты Dynamo

Запустите frontend и backend SGLang, чтобы проверить метрики:

# Start frontend (default port 8000, override with --http-port or DYN_HTTP_PORT env var)
$ python -m dynamo.frontend

# Enable system metrics server on port 8081
$ DYN_SYSTEM_PORT=8081 python -m dynamo.sglang --model <model_name> --enable-metrics

Дождитесь запуска воркера SGLang, затем отправьте запросы и проверьте метрики:

# Send a request
curl -H 'Content-Type: application/json' \
-d '{
  "model": "<model_name>",
  "max_completion_tokens": 100,
  "messages": [{"role": "user", "content": "Explain why Roger Federer is considered one of the greatest tennis players of all time"}]
}' \
http://localhost:8000/v1/chat/completions

# Check metrics from the worker
curl -s localhost:8081/metrics | grep "^sglang:"

Публикуемые метрики

SGLang публикует метрики в текстовом формате Prometheus Exposition Format на HTTP-эндпоинте /metrics. Все метрики движка SGLang используют префикс sglang: и включают метки (например, model_name, engine_type, tp_rank, pp_rank) для идентификации источника.

Пример текста в формате Prometheus Exposition Format:

# HELP sglang:prompt_tokens_total Number of prefill tokens processed.
# TYPE sglang:prompt_tokens_total counter
sglang:prompt_tokens_total{model_name="meta-llama/Llama-3.1-8B-Instruct"} 8128902.0

# HELP sglang:generation_tokens_total Number of generation tokens processed.
# TYPE sglang:generation_tokens_total counter
sglang:generation_tokens_total{model_name="meta-llama/Llama-3.1-8B-Instruct"} 7557572.0

# HELP sglang:cache_hit_rate The cache hit rate
# TYPE sglang:cache_hit_rate gauge
sglang:cache_hit_rate{model_name="meta-llama/Llama-3.1-8B-Instruct"} 0.0075

Примечание: конкретные метрики, показанные выше, являются примерами и могут различаться в зависимости от версии SGLang. Всегда проверяйте фактический эндпоинт /metrics или обращайтесь к официальной документации, чтобы получить актуальный список.

Категории метрик

SGLang предоставляет метрики в следующих категориях (все с префиксом sglang:):

Метрики пропускной способности - скорость обработки токенов
Использование ресурсов - потребление системных ресурсов
Метрики задержек - измерения задержки запросов и токенов
Метрики дезагрегации - метрики, специфичные для дезагрегированных развертываний (если включены)

Примечание: конкретные метрики могут меняться между версиями SGLang. Всегда обращайтесь к официальной документации или проверяйте эндпоинт /metrics для вашей версии SGLang.

Доступные метрики

Официальная документация SGLang содержит полные определения метрик, включая:

описания HELP и TYPE
типы метрик Counter, Gauge и Histogram
метки метрик (например, model_name, engine_type, tp_rank, pp_rank)
руководство по настройке мониторинга Prometheus + Grafana
советы по устранению неполадок и примеры конфигурации

Полный и авторитетный список всех метрик SGLang см. в официальной документации SGLang Production Metrics.

Детали реализации

SGLang использует сбор метрик в многопроцессном режиме через prometheus_client.multiprocess.MultiProcessCollector
Метрики фильтруются по префиксу sglang: перед публикацией
Интеграция использует функцию Dynamo register_engine_metrics_callback()
Метрики появляются после завершения инициализации движка SGLang

Метрики прямого прохода (FPM)

Доступность в среде выполнения SGLang 1.2.0. Опубликованный образ sglang-runtime:1.2.0 пока не включает upstream-модуль sglang.srt.observability.forward_pass_metrics и соответствующие поля ServerArgs (enable_forward_pass_metrics, forward_pass_metrics_worker_id, forward_pass_metrics_ipc_name). Установка DYN_FORWARDPASS_METRIC_PORT успешно запускает ретранслятор на стороне Dynamo, и воркер продолжает обслуживать запросы, но FPM-полезные нагрузки со стороны SGLang не отправляются в событийную плоскость NATS. Описанные ниже конвейер и схема отражают предполагаемую архитектуру и станут работоспособными после включения upstream-модуля SGLang FPM в будущий образ среды выполнения SGLang. Для масштабирования Planner на основе нагрузки в версии 1.2.0 используйте backend vLLM или TensorRT-LLM (без attention-DP); см. матрицу поддержки Planner FPM.

Forward Pass Metrics предоставляют телеметрию планировщика по каждой итерации, передаваемую через ZMQ, что дает Planner видимость в реальном времени по составу batch, глубине очереди и длительности прямого прохода на GPU. В отличие от метрик Prometheus (которые собираются асинхронно и отражают только последнее значение gauge), FPM отправляет структурированное сообщение после каждой итерации планировщика с точным состоянием batch.

Конвейер

flowchart LR
    A["SGLang Scheduler<br/>(child process)"] -->|ZMQ PUB<br/>IPC per dp_rank| B["FpmEventRelay<br/>(Rust)"]
    B -->|NATS<br/>event plane| C["FpmEventSubscriber<br/>(Rust)"]
    C --> D["Planner<br/>regression models"]

Транспорт не зависит от backend: одни и те же FpmEventRelay и FpmEventSubscriber используются backend-ами SGLang и vLLM.

Включение FPM

FPM требует, чтобы адаптер Dynamo (dynamo.sglang) внедрил идентификатор воркера и IPC-путь до инициализации движка. Это происходит автоматически, когда среда выполнения Dynamo создает воркер SGLang.

Planner подписывается на FPM через событийную плоскость NATS. Конфигурацию (load_adjustment_interval, max_num_fpm_samples, fpm_sample_bucket_size) см. в руководстве по Planner.

Схема

ForwardPassMetrics (верхний уровень, по одному на итерацию):

Field	Type	Description
`version`	`int`	Версия схемы (сейчас 1)
`worker_id`	`str`	Dynamo endpoint `connection_id`
`dp_rank`	`int`	Ранг data-parallel
`counter_id`	`int`	Монотонный порядковый номер для каждой пары (worker, dp_rank)
`wall_time`	`float`	Длительность прямого прохода на GPU в секундах (через DeviceTimer)
`scheduled_requests`	`ScheduledRequestMetrics`	Состав batch в этой итерации
`queued_requests`	`QueuedRequestMetrics`	Снимок ожидающих запросов

ScheduledRequestMetrics (запросы в этом batch):

Field	Type	Description
`num_prefill_requests`	`int`	Prefill-запросы (новые + chunked-продолжения)
`sum_prefill_tokens`	`int`	Заново вычисленные токены (размер chunk, а не полный prompt)
`var_prefill_length`	`float`	Дисперсия полных длин prompt
`sum_prefill_kv_tokens`	`int`	KV-токены, прочитанные, но не вычисленные (prefix cache + предыдущие chunks)
`num_decode_requests`	`int`	Decode-запросы, генерирующие выходные токены
`sum_decode_kv_tokens`	`int`	Общая длина KV-контекста по decode-запросам
`var_decode_kv_tokens`	`float`	Дисперсия длин decode KV-контекста

QueuedRequestMetrics (запросы, ожидающие планирования):

Field	Type	Description
`num_prefill_requests`	`int`	Prefill-запросы в очереди
`sum_prefill_tokens`	`int`	Общее число токенов по prefill в очереди
`var_prefill_length`	`float`	Дисперсия длин prefill в очереди
`num_decode_requests`	`int`	Decode-запросы в очереди
`sum_decode_kv_tokens`	`int`	Общее число KV-токенов по decode в очереди
`var_decode_kv_tokens`	`float`	Дисперсия длин decode KV в очереди

Точные по GPU измерения времени

FPM использует инфраструктуру DeviceTimer SGLang (пары событий CUDA вокруг model_runner.forward() и cuda_graph.replay()) для точного по GPU значения wall_time. Это исключает накладные расходы планирования на CPU, которые попали бы в измерение времени на уровне планировщика.

Когда события DeviceTimer еще не готовы (режим overlap scheduler, где работа GPU из итерации N все еще выполняется), FPM пропускает отправку для этой итерации, а не сообщает неточное резервное значение на основе монотонных часов.

Дезагрегированный режим

В дезагрегированном обслуживании метрики запросов в очереди читаются из правильных очередей, специфичных для движка:

Engine	Queue Source
Unified (non-disagg)	`waiting_queue`
Prefill	`disagg_prefill_bootstrap_queue`
Decode	`disagg_decode_prealloc_queue` + `disagg_decode_transfer_queue`

Контрактный тест между репозиториями

SGLang определяет собственную структуру ForwardPassMetrics, которая должна послойно совпадать с общей схемой Dynamo. Контрактный тест между репозиториями (dynamo/sglang/tests/test_fpm_contract.py) защищает от дрейфа схемы: он кодирует данные структурой SGLang и декодирует их структурой Dynamo.

Ссылка на дизайн

Полную мотивацию и обоснование дизайна см. в RFC по Forward Pass Metrics.

Распределенная трассировка

Dynamo распространяет заголовки W3C Trace Context через конвейер запросов SGLang, позволяя коррелировать трассы между frontend, router и отдельными воркерами SGLang в дезагрегированном развертывании.

Предварительные требования

Внутренняя трассировка движка SGLang требует пакеты opentelemetry. Они объявлены как extra SGLang [tracing]. Установите их в окружение Dynamo:

uv pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-exporter-otlp-proto-grpc

Без этих пакетов span-ы на стороне Dynamo (frontend, handler) по-прежнему будут работать, но внутренние span-ы движка SGLang не будут отправляться, и вы увидите предупреждение: "Tracing is disabled because the packages cannot be imported."

Как работает распространение трассировки

Frontend (Rust)
  creates span, embeds trace_id + span_id in Context
    |
    v
Dynamo RPC (NATS transport)
  Context serialized with trace_id, span_id
    |
    v
SGLang Handler (Python)
  dynamo.common.utils.otel_tracing.build_trace_headers(context)
  builds W3C traceparent: "00-{trace_id}-{span_id}-01"
    |
    v
sgl.Engine.async_generate(
    ...,
    rid=trace_id,                        # request ID = trace ID
    external_trace_header=traceparent    # W3C header for SGLang internal spans
)
    |
    v
SGLang Engine (internal spans attached to same trace)

Ключевые файлы реализации:

components/src/dynamo/common/utils/otel_tracing.py - построитель заголовка W3C traceparent
components/src/dynamo/sglang/request_handlers/handler_base.py:71-84 - извлекает контекст трассировки из объекта Dynamo Context
components/src/dynamo/sglang/request_handlers/llm/decode_handler.py - передает external_trace_header и rid=trace_id в engine.async_generate()

Переменные окружения

Variable	Description	Default	Example
`DYN_LOGGING_JSONL`	Включить логирование JSONL (требуется для трассировки)	`false`	`true`
`OTEL_EXPORT_ENABLED`	Включить экспорт трасс OTLP	`false`	`true`
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	Эндпоинт OTLP gRPC для Tempo	`http://localhost:4317`	`http://tempo:4317`
`OTEL_SERVICE_NAME`	Имя сервиса, отображаемое в Grafana Tempo	`dynamo`	`dynamo-worker-decode`

Флаги, специфичные для SGLang

Flag	Description
`--enable-trace`	Включить распространение заголовков трассировки W3C в движок SGLang
`--otlp-traces-endpoint`	Эндпоинт OTLP gRPC для внутреннего экспорта трасс SGLang (простой формат `host:port`, например `localhost:4317`)

Оба флага требуются для сквозной трассировки через движок SGLang. Без --enable-trace handler Dynamo все равно создает span-ы, но внутренние span-ы движка SGLang не будут связаны.

Управление подробностью трассировки SGLang

Когда задан --enable-trace, SGLang отправляет span-ы на четырех уровнях подробности. По умолчанию Dynamo использует уровень 2: он сохраняет все полезные span-ы по каждому запросу и при этом подавляет высокообъемный шум планировщика:

Level	Spans included	Volume
1	`tokenize`, `prefill_forward`, `decode_forward`	Низкий
2	Уровень 1 + `request_process`, `api_server_dispatch`	Низкий
3 (SGLang default)	Уровень 2 + `decode_loop`, `chunked_prefill`, `fake_output`	Очень высокий (~1.6M span-ов/час на модель)
4	Уровень 3 + `run_batch_cpu`	Чрезвычайно высокий

Используйте переменную окружения SGLANG_TRACE_LEVEL, чтобы переопределить значение по умолчанию:

Variable	Description	Default	Example
`SGLANG_TRACE_LEVEL`	Уровень подробности внутренних span-ов SGLang (1-4); активен только при заданном `--enable-trace`	`2`	`1`

# Keep only the most essential per-request spans
SGLANG_TRACE_LEVEL=1 python -m dynamo.sglang --model Qwen/Qwen3-0.6B --enable-trace --otlp-traces-endpoint localhost:4317

# Restore SGLang's default level (includes decode_loop — high volume)
SGLANG_TRACE_LEVEL=3 python -m dynamo.sglang --model Qwen/Qwen3-0.6B --enable-trace --otlp-traces-endpoint localhost:4317

Запуск с трассировкой

Скрипт запуска дезагрегированного режима поддерживает --enable-otel, чтобы включить трассировку во всех компонентах:

# Start observability stack first
docker compose -f dev/docker-compose.yml up -d
docker compose -f dev/docker-observability.yml up -d

# Launch SGLang disaggregated with tracing
cd examples/backends/sglang/launch
./disagg.sh --enable-otel

Или вручную для агрегированного развертывания:

export DYN_LOGGING_JSONL=true
export OTEL_EXPORT_ENABLED=true
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4317

# Frontend
OTEL_SERVICE_NAME=dynamo-frontend python -m dynamo.frontend &

# SGLang worker with tracing
OTEL_SERVICE_NAME=dynamo-worker-sglang \
DYN_SYSTEM_PORT=8081 \
python -m dynamo.sglang \
  --model Qwen/Qwen3-0.6B \
  --enable-metrics \
  --enable-trace \
  --otlp-traces-endpoint localhost:4317

Что вы увидите в трассах

При включенной трассировке каждый inference-запрос создает единую сквозную трассу, охватывающую полный жизненный цикл запроса:

Span frontend http-request - корневой span из HTTP-сервиса, включает method/uri/trace_id
Span-ы KV Router - kv_router.route_request, kv_router.select_worker, kv_router.compute_block_hashes, kv_router.find_matches, kv_router.compute_seq_hashes, kv_router.schedule
Span воркера handle_payload - handler Dynamo RPC на стороне воркера, с метками component/endpoint/namespace
Span-ы движка SGLang - Req <id>, Scheduler, Tokenizer, request_process, prefill_forward, decode_loop, Bootstrap Room (для disagg)
Семантические соглашения - gen_ai.usage.prompt_tokens, gen_ai.usage.completion_tokens, gen_ai.latency.time_to_first_token и т. д.

Пример дерева трассы для запроса, маршрутизируемого через KV:

dynamo-frontend: http-request (root)
  dynamo-frontend: kv_router.route_request
    dynamo-frontend: kv_router.select_worker
      kv_router.compute_block_hashes
      kv_router.find_matches
      kv_router.compute_seq_hashes
      kv_router.schedule
    dynamo-worker-1: handle_payload
      sglang: Bootstrap Room 0x0
        sglang: Req <trace-id-prefix>
          sglang: Scheduler [TP 0]
            request_process
            prefill_forward
            decode_loop (repeated per token)
          sglang: Tokenizer
            tokenize
            dispatch

Сквозная трасса в Grafana Tempo, показывающая span-ы frontend, KV router, worker и движка SGLang

Просмотр трасс

Откройте Grafana по адресу http://localhost:3000 (имя пользователя: dynamo, пароль: dynamo)
Перейдите в Explore (значок компаса)
Выберите Tempo в качестве источника данных
Используйте вкладку Search:
- фильтруйте по Service Name (например, dynamo-frontend, dynamo-worker-1, sglang)
- фильтруйте по Span Name (например, http-request, handle_payload, Req *, decode_loop)
- фильтруйте по Tags (например, rid=<trace-id>, gen_ai.response.model=Qwen/Qwen3-0.6B)
Нажмите на трассу, чтобы посмотреть flame graph, охватывающий frontend -> router -> worker -> engine

Отправьте запрос с x-request-id, чтобы его было проще найти:

curl -H 'Content-Type: application/json' \
  -H 'x-request-id: my-trace-001' \
  -d '{"model": "Qwen/Qwen3-0.6B", "max_completion_tokens": 50,
       "messages": [{"role": "user", "content": "Explain why Roger Federer is considered one of the greatest tennis players of all time"}]}' \
  http://localhost:8000/v1/chat/completions

Подробнее об инфраструктуре трассировки Tempo/Grafana см. в руководстве по трассировке Dynamo.

Панель Grafana для SGLang

Dynamo поставляется с заранее подготовленной панелью Grafana для SGLang в dev/observability/grafana_dashboards/sglang.json. Она автоматически загружается при запуске стека наблюдаемости.

Панели dashboard

Dashboard организован в пять разделов:

Section	Panels	What to Watch
Задержка запросов	E2E Request Latency, Time-To-First-Token, Inter-Token Latency	Регрессии хвостовой задержки, всплески TTFT при давлении prefill
Пропускная способность и очередь	Token Generation Throughput (tok/s), Running & Queued Requests, Request Rate	Насыщение пропускной способности, рост глубины очереди
Кэш и PIN	Cache Hit Rate, Active PIN Count, Retractions	Эффективность повторного использования KV cache, давление PIN из-за disagg-маршрутизации
Давление на память	GPU KV Cache Usage %, Host (CPU) KV Cache Usage %, Eviction & Load-back Rate	Риск OOM, активность offload HiCache
Задержка HiCache	Eviction P99 Latency, Load-back P99 Latency	Узкие места PCIe/NVLink на пути offload KV

Доступ к dashboard

Откройте Grafana по адресу http://localhost:3000
Войдите с dynamo / dynamo
Нажмите Dashboards на левой боковой панели
Выберите SGLang Engine

Другие доступные dashboard:

Dynamo Dashboard (dynamo.json) - метрики frontend и компонентов
DCGM Metrics (dcgm-metrics.json) - загрузка GPU, память, мощность
KVBM (kvbm.json) - метрики KV block manager
Disagg Dashboard (disagg-dashboard.json) - метрики дезагрегированного обслуживания

Публикация на удаленной VM

При разработке на удаленной VM (облачный инстанс, bare metal и т. д.) порты наблюдаемости привязаны только к localhost внутри VM. У вас есть два варианта доступа к ним.

Вариант 1: проброс портов SSH (рекомендуется)

Пробросьте нужные порты через SSH-соединение. Изменения firewall не нужны, трафик шифруется.

# Forward Grafana (3000), Prometheus (9090), and Tempo (3200)
ssh -L 3000:localhost:3000 \
    -L 9090:localhost:9090 \
    -L 3200:localhost:3200 \
    user@your-vm-ip

Затем откройте http://localhost:3000 в локальном браузере.

Для долговременного туннеля в фоне:

ssh -fN \
    -L 3000:localhost:3000 \
    -L 9090:localhost:9090 \
    -L 3200:localhost:3200 \
    user@your-vm-ip

Вариант 2: правила firewall

Откройте порты напрямую. Используйте это только в доверенных сетях.

# Ubuntu/Debian
sudo ufw allow 3000/tcp   # Grafana
sudo ufw allow 9090/tcp   # Prometheus

# Or for cloud VMs, add inbound rules in your security group for ports 3000, 9090

Затем откройте http://<vm-ip>:3000 напрямую.

Доступ без браузера / для агентов

Для CI-конвейеров, AI coding agents или headless-workflows, где браузер недоступен, можно обращаться к Grafana и Prometheus напрямую через их API:

# Query Prometheus for SGLang token throughput
curl -s 'http://localhost:9090/api/v1/query?query=rate(sglang:generation_tokens_total[1m])' | python3 -m json.tool

# Query Prometheus for GPU KV cache usage
curl -s 'http://localhost:9090/api/v1/query?query=dynamo_component_gpu_cache_usage_percent' | python3 -m json.tool

# List available Grafana dashboards
curl -s -u dynamo:dynamo http://localhost:3000/api/search | python3 -m json.tool

# Get the SGLang dashboard by title
curl -s -u dynamo:dynamo 'http://localhost:3000/api/search?query=SGLang' | python3 -m json.tool

# Fetch a specific dashboard by UID
curl -s -u dynamo:dynamo http://localhost:3000/api/dashboards/uid/<dashboard-uid> | python3 -m json.tool

# Snapshot current metrics via Prometheus range query (last hour)
START=$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)
END=$(date -u +%Y-%m-%dT%H:%M:%SZ)
curl -s "http://localhost:9090/api/v1/query_range?query=sglang:cache_hit_rate&start=${START}&end=${END}&step=15s"

Это полезно для автоматизированных конвейеров бенчмаркинга, где нужно программно сохранять метрики вместе с результатами производительности.

Связанная документация

Метрики SGLang