Spans y métricas recopiladas para vLLM y SGLang - Application Real-Time Monitoring Service

Cuando el agente de Python de ARMS instrumenta un motor de inference vLLM o SGLang, reporta spans, atributos de span, eventos de span y métricas de las solicitudes de inference que procesa el motor. Utilice este tema para identificar la etapa de ejecución que representa cada span en una traza, qué mide cada atributo y cómo se calcula cada métrica. Si una solicitud se vuelve lenta o una métrica del panel no coincide con lo esperado, estas descripciones le ayudarán a analizar trazas, compilar paneles de métricas y localizar problemas de rendimiento.

Convenciones comunes de los spans

El SpanKind de cada span es INTERNAL. Los spans que genera el agente expresan su semántica de negocio mediante el atributo gen_ai.span.kind, el cual toma el valor LLM, EMBEDDING o RERANKER. Los spans generados por la instrumentación nativa del motor no incluyen este atributo, por lo que la etapa se identifica a partir del nombre del span.

Mapeo de nombres de campos entre motores y versiones

Los campos con la misma semántica usan nombres distintos según el motor, la versión del motor y la capa de recopilación. A continuación se muestra una tabla que mapea los nombres de campo equivalentes:

Semántica	Nombre del campo	Reportado por
Número de tokens de entrada	`gen_ai.usage.input_tokens`	Spans de entrada de vLLM y spans de entrada de SGLang
Número de tokens de entrada	`gen_ai.usage.prompt_tokens`	Spans `llm_request` de vLLM V0 y V1, y spans de solicitud nativos de SGLang
Número de tokens de salida	`gen_ai.usage.output_tokens`	Spans de entrada de vLLM y spans de entrada de SGLang
Número de tokens de salida	`gen_ai.usage.completion_tokens`	Spans `llm_request` de vLLM V0 y V1, y spans de solicitud nativos de SGLang
Número de candidatos	`gen_ai.request.choice.count`	Spans de entrada de vLLM y spans de entrada de SGLang
Número de candidatos	`gen_ai.request.n`	Spans `llm_request` de vLLM V0 y V1, y spans de solicitud nativos de SGLang
Nombre del modelo	`gen_ai.request.model`	Spans de entrada de vLLM y spans de entrada de SGLang
Nombre del modelo	`gen_ai.request.model_name`	Spans `llm_request` de vLLM V1
Nombre del modelo	`model_name` (dimensión de métrica)	Métricas del lado del motor de vLLM V1
Nombre del modelo	`modelName` (dimensión de métrica)	Métricas de tokens de la capa API de vLLM y métricas de consumo de tokens de SGLang
Tokens de entrada servidos desde la caché	`gen_ai.usage.cache_read.input_tokens`	Spans `llm_request` de vLLM V1 y spans de entrada de SGLang
Tokens de entrada servidos desde la caché	`gen_ai.usage.cached_tokens`	Spans de solicitud nativos de SGLang
Tiempo hasta el primer token (métrica)	`genai_llm_first_token_seconds`	Métricas de vLLM
Tiempo hasta el primer token (métrica)	`gen_ai_server_time_to_first_token`	Métricas de SGLang

Spans de vLLM

Lista de spans

Nombre del span	Se produce en	Descripción
`chat {model name}`	Capa API compatible con OpenAI	Punto de entrada de una solicitud de Chat Completions, `/v1/chat/completions`.
`text_completion {model name}`	Capa API compatible con OpenAI	Punto de entrada de una solicitud de Completions, `/v1/completions`.
`embeddings {model name}`	Capa API compatible con OpenAI	Punto de entrada de una solicitud de embedding.
`rerank {model name}`	Capa API compatible con OpenAI	Punto de entrada de una solicitud de rerank o score.
`llm_request`	Dentro del motor	Ciclo de vida completo de una solicitud dentro del motor. Lo producen tanto V0 como V1.
`wait`	Dentro del motor	Tiempo que una solicitud espera en la cola para ser programada. Solo V1, con granularidad de recopilación de 1 o superior.
`kv_transfer`	Dentro del motor	Duración de la extracción de la caché KV desde el lado remoto. Anidado bajo `wait`. Solo V1, con granularidad de recopilación de 1 o superior.
`prefill`	Dentro del motor	Duración de la etapa Prefill. Solo V1, con granularidad de recopilación de 1 o superior.
`decode`	Dentro del motor	Duración de la etapa Decode. Solo V1, con granularidad de recopilación de 1 o superior.

El span kv_transfer se anida dentro de wait en lugar de colocarse junto a él. Mientras vLLM espera la caché KV remota, la solicitud permanece en el estado WAITING_FOR_REMOTE_KVS, por lo que la duración de la transferencia queda dentro de la ventana de espera.

Nota

El tiempo real en la cola equivale a la duración de wait menos la duración de kv_transfer.

En un despliegue PD-disaggregated, un nodo Prefill solo produce el span hijo prefill, mientras que un nodo Decode únicamente genera el span hijo decode.

Atributos del span de entrada

La instrumentación general de GenAI genera los spans de entrada. Sus definiciones de atributos son consistentes con la instrumentación de otros frameworks de modelos de lenguaje grandes.

Atributo	Descripción
`gen_ai.span.kind`	Tipo semántico de negocio. `LLM`, `EMBEDDING` o `RERANKER`.
`gen_ai.operation.name`	Tipo de operación. `chat`, `text_completion`, `embeddings` o `rerank`.
`gen_ai.request.model`	Nombre del modelo especificado en la solicitud.
`gen_ai.request.choice.count`	Número de candidatos solicitados, que corresponde al parámetro `n`.
`gen_ai.request.temperature`	Temperatura de muestreo.
`gen_ai.request.top_p`	Parámetro Top-P.
`gen_ai.request.top_k`	Parámetro Top-K.
`gen_ai.request.max_tokens`	Número máximo de tokens por generar.
`gen_ai.request.is_stream`	Indica si la solicitud es de streaming.
`gen_ai.user.id`	Campo `user` que transporta la solicitud.
`session.id`	Identificador de la solicitud en escenarios de streaming.
`gen_ai.response.id`	ID de la respuesta.
`gen_ai.response.model`	Nombre del modelo devuelto en la respuesta.
`gen_ai.response.finish_reasons`	Motivos de finalización.
`gen_ai.usage.input_tokens`	Número de tokens de entrada.
`gen_ai.usage.output_tokens`	Número de tokens de salida.
`gen_ai.usage.total_tokens`	Número total de tokens.
`gen_ai.input.messages`	Contenido de entrada. Controlado por el interruptor de recopilación de contenido.
`gen_ai.output.messages`	Contenido de salida. Controlado por el interruptor de recopilación de contenido.

Atributos del span `llm_request` (V0)

La unidad de los atributos de duración de un motor V0 es segundos.

Atributo	Descripción
`gen_ai.request.id`	ID interno de la solicitud del motor.
`gen_ai.response.model`	Nombre del modelo.
`gen_ai.request.temperature`	Temperatura de muestreo.
`gen_ai.request.top_p`	Parámetro Top-P.
`gen_ai.request.max_tokens`	Número máximo de tokens por generar.
`gen_ai.request.n`	Número de candidatos.
`gen_ai.usage.num_sequences`	Número de secuencias.
`gen_ai.usage.prompt_tokens`	Número de tokens de entrada.
`gen_ai.usage.completion_tokens`	Número de tokens de salida.
`gen_ai.latency.e2e`	Duración de extremo a extremo de la solicitud.
`gen_ai.latency.time_in_queue`	Duración en la cola.
`gen_ai.latency.time_to_first_token`	Tiempo hasta el primer token.
`gen_ai.latency.time_in_scheduler`	Duración de la programación. Se reporta solo cuando el motor proporciona estos datos.
`gen_ai.latency.time_in_model_forward`	Duración del cálculo forward del modelo. Se reporta solo cuando el motor proporciona estos datos.
`gen_ai.latency.time_in_model_execute`	Duración de la ejecución del modelo, que incluye el cálculo forward, la sincronización entre workers, la sincronización CPU-GPU y el muestreo. Se reporta solo cuando el motor proporciona estos datos.

Atributos del span `llm_request` (V1)

La unidad de los atributos de duración de un motor V1 es nanosegundos.

Atributo	Descripción
`gen_ai.request.id`	ID interno de la solicitud del motor.
`gen_ai.request.model_name`	Nombre del modelo.
`gen_ai.request.temperature`	Temperatura de muestreo.
`gen_ai.request.top_p`	Parámetro Top-P.
`gen_ai.request.max_tokens`	Número máximo de tokens por generar.
`gen_ai.request.n`	Número de candidatos.
`gen_ai.usage.prompt_tokens`	Número de tokens de entrada.
`gen_ai.usage.completion_tokens`	Número de tokens de salida.
`gen_ai.usage.cache_read.input_tokens`	Número de tokens de entrada servidos desde la caché sin volver a aplicar prefill, lo que incluye aciertos de la caché de prefijo local y la reutilización de KV remota. Se reporta incluso cuando el valor es 0, para que pueda calcular la tasa de aciertos de la caché.
`gen_ai.latency.e2e`	Duración de extremo a extremo de la solicitud.
`gen_ai.latency.time_in_queue`	Duración en la cola.
`gen_ai.latency.time_to_first_token`	Tiempo hasta el primer token.
`gen_ai.latency.time_in_model_prefill`	Duración de la etapa Prefill.
`gen_ai.latency.time_in_model_decode`	Duración de la etapa Decode.
`gen_ai.latency.time_in_model_inference`	Duración total de las etapas de inference (Prefill + Decode).
`gen_ai.latency.time_in_tokenize`	Duración de la tokenización del prompt, que ocurre en el proceso de frontend.
`gen_ai.latency.time_in_detokenize`	Duración acumulada incremental de la detokenización.
`gen_ai.latency.time_in_kv_transfer`	Duración total de las transferencias de caché KV remota. Se reporta solo cuando ocurrió una transferencia.
`gen_ai.request.preemption_count`	Número de veces que se interrumpió la solicitud por preemptión. Se reporta solo cuando hubo preemptión.
`gen_ai.engine.index`	Índice de la instancia EngineCore, que distingue los motores en un despliegue multimotor.
`gen_ai.pd_role`	Rol de desagregación PD. `producer` (nodo Prefill), `consumer` (nodo Decode) o `none` (no es un despliegue PD-disaggregated).

Nota

Con la desagregación PD, solo la duración de Prefill es precisa en un nodo Prefill (time_in_model_decode siempre es 0), y solo la duración de Decode es precisa en un nodo Decode (time_in_model_prefill siempre es 0). vLLM no restablece la marca de tiempo de programación cuando interrumpe una solicitud por preemptión, por lo que las duraciones de Prefill, Decode e Inference ya incluyen las pausas causadas por dicha preemptión. El atributo gen_ai.request.preemption_count sirve como evidencia para explicar esos picos de duración.

Atributos de los spans hijos de etapa

Los cuatro spans hijos wait, kv_transfer, prefill y decode incluyen gen_ai.request.id, gen_ai.request.model_name, gen_ai.engine.index y gen_ai.pd_role. El span kv_transfer lleva los siguientes atributos adicionales:

Atributo	Descripción
`gen_ai.kv_transfer.direction`	Dirección de la transferencia. El valor es `recv`, lo que significa que el nodo Decode extrae la caché KV.
`gen_ai.kv_transfer.cached_tokens`	Número de tokens cubiertos por esta transferencia, equivalente a los tokens resueltos en el lado remoto del conector.
`gen_ai.kv_transfer.failed`	Indica si el conector reportó un error de carga para esta solicitud.

Eventos de span

Cuando la granularidad de recopilación es 2, se agregan eventos de span a llm_request por cada iteración de programación del motor. Esto permite reconstruir el proceso de ejecución iteración por iteración.

Nombre del evento	Descripción
`WAIT`	La solicitud entra en estado de espera.
`PREFILL`	Una iteración de Prefill.
`DECODE`	Una iteración de Decode.
`PREEMPTED`	La solicitud se interrumpe por preemptión para liberar bloques de caché KV.

Los atributos de los eventos incluyen gen_ai.engine.index y la información a nivel de token gen_ai.token.ids, gen_ai.token.texts, gen_ai.token.count y gen_ai.token.logprobs.

Nota

La cantidad de eventos es proporcional al número de iteraciones de la solicitud y puede superar fácilmente el límite predeterminado de OpenTelemetry de 128 eventos por span; en ese caso, los eventos se descartan. Incremente OTEL_SPAN_EVENT_COUNT_LIMIT cuando sea necesario.

Métricas de vLLM

Dimensiones de las métricas

Dimensiones comunes que incluyen las métricas del lado del motor de vLLM:

Dimensión	Descripción
`callType`	Siempre `gen_ai`.
`rpcType`	Siempre `2100`.
`engine_index`	Índice de la instancia EngineCore. Solo V1.
`model_name`	Nombre del modelo. Solo V1.

La métrica gen_ai_vllm_request_success incluye la dimensión adicional finished_reason. Las métricas de tokens de la capa API llevan las siguientes dimensiones:

Dimensión	Descripción
`callType`	Siempre `gen_ai`.
`callKind`	Siempre `custom_entry`.
`rpcType`	Siempre `2100`.
`modelName`	Nombre del modelo.
`spanKind`	`LLM` o `EMBEDDING`.
`usageType`	`input` o `output`.

Métricas comunes

Los motores V0 y V1 reportan las siguientes métricas:

Nombre de la métrica	Tipo	Unidad	Descripción
`genai_llm_usage_tokens`	Counter	Count	Consumo de tokens de entrada y salida, diferenciado por `usageType`.
`vllm_iter_count`	Counter	Times	Número de iteraciones de programación del motor.
`gen_ai_vllm_request_success`	Counter	Times	Número de solicitudes completadas correctamente.
`genai_llm_first_token_seconds`	Counter	Seconds	Tiempo acumulado hasta el primer token.
`gen_ai_server_time_per_output_token`	Counter	Seconds	Tiempo acumulado por token de salida.
`gen_ai_server_request_duration`	Counter	Seconds	Duración acumulada de extremo a extremo de las solicitudes.

Métricas de V0

Las métricas de estado del sistema son gauges y reflejan el valor instantáneo en el momento de la recopilación.

Nombre de la métrica	Tipo	Unidad	Descripción
`gpu_cache_usage_sys`	Gauge	Ratio	Uso de la caché KV de GPU.
`cpu_cache_usage_sys`	Gauge	Ratio	Uso de la caché KV de CPU.
`num_running_sys`	Gauge	Count	Número de secuencias en ejecución.
`num_waiting_sys`	Gauge	Count	Número de secuencias en espera.
`num_swapped_sys`	Gauge	Count	Número de secuencias intercambiadas hacia afuera (swapped-out).
`num_prompt_tokens_iter`	Counter	Count	Número de tokens de entrada procesados en la iteración.
`num_generation_tokens_iter`	Counter	Count	Número de tokens de salida generados en la iteración.
`num_tokens_iter`	Counter	Count	Número total de tokens procesados en la iteración.
`num_preemption_iter`	Counter	Times	Número de preemptions en la iteración.

Nota

Las métricas de tipo gauge solo las reportan los procesos que reciben estadísticas de programación del motor. Los procesos que no participan en la inference, como los procesos puros de frontend, no reportan valores de 0. Esto evita curvas planas en cero sin sentido en un despliegue multiproceso.

Métricas de V1

Nombre de la métrica	Tipo	Unidad	Descripción
`gen_ai_vllm_num_requests_running`	Gauge	Count	Número de solicitudes en el lote en ejecución.
`gen_ai_vllm_num_requests_waiting`	Gauge	Count	Número de solicitudes en espera de procesamiento.
`gen_ai_vllm_kv_cache_usage_perc`	Gauge	Ratio	Uso de la caché KV, en el rango [0,1].
`gen_ai_vllm_prefix_cache_queries`	Counter	Count	Número de tokens consultados en la caché de prefijo.
`gen_ai_vllm_prefix_cache_hits`	Counter	Count	Número de tokens que obtuvieron un acierto en la caché de prefijo.
`gen_ai_vllm_num_preemptions`	Counter	Times	Número acumulado de preemptions del motor.
`gen_ai_vllm_prompt_tokens`	Counter	Count	Número de tokens procesados por Prefill.
`gen_ai_vllm_generation_tokens`	Counter	Count	Número de tokens generados.
`gen_ai_vllm_request_params_n`	Counter	Count	Valor acumulado del parámetro `n` de la solicitud.
`gen_ai_vllm_request_params_max_tokens`	Counter	Count	Valor acumulado del parámetro `max_tokens` de la solicitud.
`gen_ai_vllm_request_queue_time_seconds`	Counter	Seconds	Duración acumulada de las solicitudes en la etapa WAITING.
`gen_ai_vllm_request_prefill_time_seconds`	Counter	Seconds	Duración acumulada de la etapa Prefill de las solicitudes.
`gen_ai_vllm_request_decode_time_seconds`	Counter	Seconds	Duración acumulada de la etapa Decode de las solicitudes.
`gen_ai_vllm_request_inference_time_seconds`	Counter	Seconds	Duración acumulada de las solicitudes en la etapa RUNNING.

La tasa de aciertos de la caché de prefijo se calcula dividiendo gen_ai_vllm_prefix_cache_hits entre gen_ai_vllm_prefix_cache_queries.

Spans de SGLang

Composición y jerarquía de los spans

Una traza en un escenario de SGLang consta de dos tipos de spans: los spans de entrada que genera el agente en la capa API compatible con OpenAI y los spans que produce la instrumentación nativa de SGLang. El agente inyecta el contexto del span de entrada en el encabezado de la solicitud que envía al motor, de modo que los spans nativos quedan bajo el span de entrada y forman una traza completa:

chat {model name}                             ← agent entry span
└─ Req {first 8 characters of the request ID} ← native request span, one per request
   ├─ Tokenizer (host:… | pid:…)              ← native thread span, frontend process
   │  ├─ tokenize
   │  └─ api_server_dispatch
   └─ Scheduler [TP 0] (host:… | pid:…)       ← native thread span, scheduler process
      ├─ prefill_waiting
      ├─ prefill_forward
      │  └─ chunked_prefill
      └─ decode_forward
         └─ decode_loop

La instrumentación nativa utiliza una estructura de tres niveles: solicitud, hilo y etapa. Un span de solicitud representa una solicitud completa. Un span de hilo representa cada proceso o hilo que participa en el procesamiento de la solicitud. Un span de etapa representa una parte de la lógica de procesamiento dentro de ese hilo. En un despliegue multi-GPU que usa paralelismo de tensores (TP), paralelismo de canalización (PP) o paralelismo de datos (DP), una solicitud tiene varios spans de hilo, uno por cada proceso de programación. Se establecen vínculos de span entre spans de etapa contiguos dentro del mismo hilo y entre spans de etapa conectados entre procesos, lo que permite reconstruir el orden de ejecución. Un vínculo de span no es una relación padre-hijo.

Lista de spans de entrada

La instrumentación de entrada del agente produce exactamente un span por cada solicitud y no genera spans hijos. El desglose de etapas dentro de una solicitud lo proporciona la instrumentación nativa.

Nombre del span	Descripción
`chat {model name}`	Solicitud de Chat Completions, `/v1/chat/completions`.
`text_completion {model name}`	Solicitud de Completions, `/v1/completions`.

Atributos del span de entrada

Atributos del lado de la solicitud:

Atributo	Descripción
`gen_ai.span.kind`	Siempre `LLM`.
`gen_ai.operation.name`	`chat` o `text_completion`.
`gen_ai.request.model`	Nombre del modelo especificado en la solicitud.
`gen_ai.request.id`	ID de la solicitud. Se reporta en escenarios de streaming de Chat.
`gen_ai.request.is_stream`	Indica si la solicitud es de streaming.
`gen_ai.request.temperature`	Temperatura de muestreo.
`gen_ai.request.top_p`	Parámetro Top-P.
`gen_ai.request.top_k`	Parámetro Top-K.
`gen_ai.request.max_tokens`	Número máximo de tokens por generar.
`gen_ai.request.choice.count`	Número de candidatos.

Atributos del lado de la respuesta:

Atributo	Descripción
`gen_ai.response.id`	ID de la respuesta.
`gen_ai.response.model`	Nombre del modelo devuelto en la respuesta. Se reporta en escenarios sin streaming.
`gen_ai.response.finish_reasons`	Motivos de finalización.
`gen_ai.usage.input_tokens`	Número de tokens de entrada.
`gen_ai.usage.output_tokens`	Número de tokens de salida.
`gen_ai.usage.total_tokens`	Número total de tokens.
`gen_ai.usage.cache_read.input_tokens`	Número de tokens de entrada servidos desde la caché.
`gen_ai.latency.e2e`	Duración de extremo a extremo de la solicitud, en segundos.
`gen_ai.response.tokens_streamed`	Número estimado de tokens de salida en un escenario de streaming, calculado como el número de incrementos de streaming multiplicado por el `stream_interval` del motor. Rellena `gen_ai.usage.output_tokens` cuando el servidor no devuelve usage.
`gen_ai.input.messages`	Contenido de entrada. Controlado por el interruptor de recopilación de contenido.
`gen_ai.output.messages`	Contenido de salida. Controlado por el interruptor de recopilación de contenido.

Atributos de llamada a herramientas (escenarios de streaming de Chat):

Atributo	Descripción
`gen_ai.request.has_tool_calls`	Indica si la solicitud declara herramientas.
`gen_ai.request.tool_call_detected`	Indica si se detectó una llamada a herramienta en la respuesta.
`gen_ai.request.tool_calls_count`	Número de llamadas a herramientas detectadas.
`gen_ai.completions.{i}.tool_calls.{j}.name`	Nombre de la llamada a herramienta `j` en el candidato `i`.
`gen_ai.completions.{i}.tool_calls.{j}.arguments`	Argumentos de esa llamada a herramienta.

Los spans de entrada no generan eventos de span personalizados. Cuando la política de recopilación de contenido se establece en event, el contenido de entrada y salida se reporta como un evento de registro gen_ai.client.inference.operation.details en lugar de escribirse en los atributos del span.

Habilitación de la instrumentación nativa y niveles de recopilación

El agente activa el interruptor de trazado nativo de SGLang cuando inicia el motor, por lo que no necesita agregar --enable-trace manualmente. Los spans nativos se reportan a través del TracerProvider global registrado por el agente, así que tampoco es necesario configurar --otlp-traces-endpoint. Además, los spans nativos pertenecen a la misma aplicación que los spans de entrada.

La instrumentación nativa define un nivel de recopilación para cada span de etapa, controlado por la variable de entorno SGLANG_TRACE_LEVEL. El valor predeterminado 3 reporta todos los spans de etapa de los niveles 1 al 3. Un valor menor conserva solo las etapas más críticas, y 0 desactiva la instrumentación nativa. El motor también proporciona la operación /set_trace_level?level=N para ajustar este valor dinámicamente en tiempo de ejecución. La cantidad de spans nativos crece con la escala del despliegue, y una sola solicitud produce más de 10 spans en un despliegue multi-GPU. Cuando el volumen de datos de trazas es alto, reduzca primero SGLANG_TRACE_LEVEL.

Spans de solicitud y spans de hilo

El span de solicitud es el span raíz de la instrumentación nativa. Se crea y finaliza en el proceso de frontend, y su nombre sigue el formato {role} Req {first 8 characters of the request ID}. El rol es prefill o decode bajo desagregación PD, y está vacío en un despliegue sin PD.

Atributo	Descripción
`rid`	ID de la solicitud.
`module`	Siempre `sglang::request`.
`bootstrap_room`	Identificador de correlación de la solicitud bajo desagregación PD. Es una cadena hexadecimal y solo se reporta en escenarios PD.
`gen_ai.request.id`	ID de la solicitud.
`gen_ai.request.temperature`	Temperatura de muestreo.
`gen_ai.request.top_p`	Parámetro Top-P.
`gen_ai.request.top_k`	Parámetro Top-K.
`gen_ai.request.n`	Número de candidatos.
`gen_ai.request.max_tokens`	Número máximo de tokens por generar.
`gen_ai.response.model`	Nombre del modelo configurado en el servidor.
`gen_ai.response.finish_reasons`	Motivos de finalización, como una cadena de arreglo JSON.
`gen_ai.usage.prompt_tokens`	Número de tokens de entrada.
`gen_ai.usage.completion_tokens`	Número de tokens de salida. Se reporta para solicitudes distintas a las de embedding.
`gen_ai.usage.cached_tokens`	Número de tokens de entrada servidos desde la caché.
`gen_ai.latency.time_to_first_token`	Tiempo hasta el primer token.
`gen_ai.latency.e2e`	Duración de extremo a extremo de la solicitud.
`gen_ai.latency.time_in_model_prefill`	Duración desde la finalización del envío de la solicitud hasta el primer token.
`gen_ai.latency.time_in_model_decode`	Duración desde el primer token hasta el final de la solicitud.
`gen_ai.latency.time_in_model_inference`	Duración desde la finalización del envío de la solicitud hasta el final de la solicitud.

La unidad de todos los atributos de duración es segundos. Los atributos de un span de solicitud solo se llenan cuando la solicitud termina normalmente.

Nota

Los atributos de duración son diferencias de tiempo medidas desde la perspectiva del proceso de frontend, por lo que no equivalen exactamente a las duraciones reales del cálculo forward dentro del programador. Para conocer estas últimas, consulte las duraciones reales de los spans de etapa.

El nombre de un span de hilo sigue el formato {thread label} [TP n] [PP n] [DP n] (host:{host identifier} | pid:{thread ID}). La información de rank se agrega solo cuando existe el valor correspondiente. La etiqueta del hilo es Tokenizer, MultiTokenizer-{number}, DP Controller o Scheduler, y lleva un prefijo Prefill o Decode bajo desagregación PD. El proceso Detokenizer no cuenta con instrumentación nativa, por lo que no aparece ningún span de hilo correspondiente.

Atributo	Descripción
`host_id`	Identificador único del host, que distingue procesos con el mismo PID en nodos diferentes.
`pid`	ID del hilo.
`thread_label`	Etiqueta del hilo.
`tp_rank`	Rank de paralelismo de tensores. Se reporta cuando existe.
`pp_rank`	Rank de paralelismo de canalización. Se reporta cuando existe.
`dp_rank`	Rank de paralelismo de datos. Se reporta cuando existe.

Nota

Cuando una solicitud termina de forma anómala, el estado de error y el motivo de finalización se registran en el span de hilo: su estado se establece en ERROR y se agregan los atributos relacionados con el motivo de finalización. El span de solicitud en sí no se marca como error. Al investigar una solicitud que terminó con errores, compruebe el estado de los spans de hilo.

Lista de spans de etapa

En las tablas a continuación, la columna Level corresponde a SGLANG_TRACE_LEVEL. No se genera ningún span cuyo valor de nivel sea mayor que el valor configurado.

Etapas comunes:

Nombre del span	Level	Proceso que lo genera	Descripción
`tokenize`	1	Frontend	Duración de la tokenización del prompt.
`api_server_dispatch`	2	Frontend	Duración del envío de la solicitud desde el frontend hacia el scheduler.
`dpc_dispatch`	2	DP Controller	Duración del envío de la solicitud por parte del controlador de paralelismo de datos. Se genera solo cuando DP está habilitado.
`request_process`	2	Scheduler	Duración del procesamiento desde que la solicitud entra al scheduler hasta que ingresa a la cola de espera. Solo en un despliegue sin separación PD.
`prefill_waiting`	1	Scheduler	Tiempo que la solicitud espera en la cola hasta que se programa para Prefill.
`prefill_forward`	1	Scheduler	Duración del cálculo forward de Prefill.
`chunked_prefill`	3	Scheduler	Duración de Prefill para un chunk. Anidado dentro de `prefill_forward`.
`decode_waiting`	1	Scheduler	Espera entre la finalización de Prefill y la programación del primer Decode.
`decode_forward`	1	Scheduler	Duración total de la etapa Decode.
`decode_loop`	3	Scheduler	Duración de una iteración de Decode. Anidado dentro de `decode_forward`.

Nota

decode_forward no tiene un punto de finalización independiente. Se cierra junto con el hilo cuando concluye la solicitud, por lo que su duración abarca todo el intervalo desde la primera programación de Decode hasta el final de la solicitud.

Etapas de decodificación especulativa. Se generan cuando la decodificación especulativa está habilitada y se anidan dentro de los spans forward:

Nombre del span	Level	Descripción
`spec_draft`	2	Duración de la generación de tokens candidatos por parte del modelo draft.
`spec_verify`	2	Duración de la verificación de los tokens draft por parte del modelo objetivo.
`spec_draft_extend`	3	Duración de la etapa extend del modelo draft.

Etapas de paralelismo de pipeline:

Nombre del span	Level	Descripción
`run_batch_cpu`	4	Duración del procesamiento de lotes en la CPU bajo paralelismo de pipeline. El nivel 4 es mayor que el valor predeterminado 3, por lo que este span se genera solo si usted establece explícitamente `SGLANG_TRACE_LEVEL=4`.

Etapas adicionales en un despliegue con separación PD, nodo Prefill:

Nombre del span	Level	Descripción
`prefill_prepare`	1	Duración de la preparación después de que el nodo Prefill recibe la solicitud.
`prefill_bootstrap`	1	Duración del establecimiento de la conexión de transferencia con el nodo Decode.
`prefill_transfer_kv_cache`	1	Duración de la transferencia de la caché KV al nodo Decode.

Etapas adicionales en un despliegue con separación PD, nodo Decode:

Nombre del span	Level	Descripción
`decode_prepare`	1	Duración de la preparación después de que el nodo Decode recibe la solicitud.
`decode_bootstrap`	1	Duración del establecimiento de la conexión de transferencia con el nodo Prefill.
`decode_transferred`	1	Duración de la espera para que finalice la transferencia de la caché KV.
`fake_output`	3	Duración de la finalización de la salida de la etapa Prefill por parte del nodo Decode.

Nota

Con la separación PD, Prefill y Decode tienen cada uno un span de solicitud independiente, lo que forma dos trazas independientes. Estas trazas se correlacionan como una sola solicitud mediante el atributo bootstrap_room en los spans de solicitud. En un nodo Decode dentro de un despliegue con separación PD, decode_waiting cambia su significado y representa la espera en la cola entre la finalización de la transferencia de la caché KV y el inicio del cálculo forward. Esto difiere de su significado en un despliegue sin separación PD.

Atributos y eventos de los spans de etapa

De forma predeterminada, los spans de etapa no incluyen atributos personalizados, con las tres excepciones siguientes:

Nombre del span	Atributo	Descripción
`decode_loop`	`decode_ct`	Número de la iteración actual de Decode.
`spec_verify`	`num_correct_drafts`	Cantidad de tokens draft que aprueban esta verificación. `accepted_tokens` es un alias compatible con el mismo valor.
`run_batch_cpu`	`pp_mb_id`	Número de micro-lote del paralelismo de pipeline.

La instrumentación nativa genera dos tipos de eventos de span:

Nombre del evento	Level	Atributos	Descripción
`retract`	1	Ninguna	Se registra cuando una solicitud se revierte y vuelve a la cola por falta de recursos.
`schedule`	3	`bid`, `batch_size`, `forward_mode`	Se registra cuando una solicitud se coloca en un lote. `bid` es el identificador del lote y `forward_mode` toma el valor `decode`, `prefill` o `prebuilt`.

Nota

Un evento se asigna por marca de tiempo al span de etapa cuyo intervalo cubre ese momento. Si un evento queda fuera de todos los intervalos de etapa, se adjunta al span del hilo. Por lo tanto, los eventos con el mismo nombre pueden adjuntarse en posiciones distintas según la solicitud.

Métricas de SGLang

Dimensiones de las métricas

Dimensiones que incluyen las métricas del lado del motor, correspondientes a las estadísticas del scheduler y del frontend:

Dimensión	Descripción
`callType`	Siempre `gen_ai`.
`callKind`	Siempre `custom_entry`.
`rpcType`	Siempre `2100`.

Las métricas de consumo de tokens incluyen además las dimensiones modelName, spanKind y usageType (input o output).

Lista de métricas

Nombre de la métrica	Tipo	Unidad	Descripción
`genai_llm_usage_tokens`	Counter	Count	Consumo de tokens de entrada y salida, diferenciado por `usageType`.
`sglang_num_running_reqs`	Counter	Count	Instantánea de la cantidad de solicitudes en ejecución.
`sglang_num_queue_reqs`	Counter	Count	Instantánea de la cantidad de solicitudes en la cola.
`sglang_num_used_tokens`	Counter	Count	Instantánea de la cantidad de tokens en uso actualmente.
`sglang_token_usage`	Counter	Ratio	Instantánea del uso de tokens de la caché KV.
`sglang_gen_throughput`	Counter	Tokens/s	Instantánea del rendimiento de generación.
`gen_ai_sglang_cache_hit_rate`	Counter	Ratio	Instantánea de la tasa de aciertos de caché. Se reporta solo cuando el motor proporciona este campo.
`sglang_spec_accept_length`	Counter	Count	Longitud de aceptación de la decodificación especulativa.
`sglang_log_count`	Counter	Times	Cantidad de reportes estadísticos, utilizada para calcular el promedio de las métricas de instantánea anteriores.
`prompt_tokens_total`	Counter	Count	Cantidad acumulada de tokens de entrada.
`generation_tokens_total`	Counter	Count	Cantidad acumulada de tokens de salida.
`gen_ai_sglang_cached_tokens_total`	Counter	Count	Cantidad acumulada de tokens de entrada servidos desde la caché.
`num_requests_total`	Counter	Times	Cantidad acumulada de solicitudes.
`gen_ai_server_time_to_first_token`	Counter	Seconds	Tiempo acumulado hasta el primer token.
`gen_ai_server_time_per_output_token`	Counter	Seconds	Tiempo acumulado por token de salida.
`sglang_inter_token_latency_seconds`	Counter	Seconds	Latencia acumulada entre tokens.
`gen_ai_server_request_duration`	Counter	Seconds	Duración acumulada de extremo a extremo de las solicitudes.

Nota

Las métricas de estado del sistema de SGLang se reportan como contadores, pero semánticamente cada valor es una instantánea de un periodo estadístico. En un panel de control, calcule el promedio dentro del periodo junto con sglang_log_count en lugar de leer directamente el valor acumulado.

gen_ai_server_time_per_output_token es la duración de extremo a extremo dividida entre la cantidad de tokens de salida, por lo que representa un promedio. Para observar el intervalo real entre tokens, utilice sglang_inter_token_latency_seconds.

Convenciones comunes de los spans

Mapeo de nombres de campos entre motores y versiones

Spans de vLLM

Lista de spans

Atributos del span de entrada

Atributos del span llm_request (V0)

Atributos del span llm_request (V1)

Atributos de los spans hijos de etapa

Eventos de span

Métricas de vLLM

Dimensiones de las métricas

Métricas comunes

Métricas de V0

Métricas de V1

Spans de SGLang

Composición y jerarquía de los spans

Lista de spans de entrada

Atributos del span de entrada

Habilitación de la instrumentación nativa y niveles de recopilación

Spans de solicitud y spans de hilo

Lista de spans de etapa

Atributos y eventos de los spans de etapa

Métricas de SGLang

Dimensiones de las métricas

Lista de métricas

Atributos del span `llm_request` (V0)

Atributos del span `llm_request` (V1)