vLLM および SGLang のスパンとメトリクス - Application Real-Time Monitoring Service

Application Real-Time Monitoring Service (ARMS) Python エージェントは、vLLM または SGLang の推論エンジンをインストルメントすると、エンジンが処理する推論リクエストのスパン、スパン属性、スパンイベント、およびメトリクスを報告します。このトピックでは、トレース内の各スパンが表す実行段階、各属性が測定する内容、および各メトリックの計算方法を特定できます。リクエストの速度が低下したり、ダッシュボードのメトリックが期待値と一致しない場合、これらの説明を参考に、トレースを分析し、メトリックダッシュボードを構築し、パフォーマンスの問題を特定できます。

共通のスパン規約

すべてのスパンの SpanKind は INTERNAL です。エージェントが生成するスパンは、値として LLM、EMBEDDING、または RERANKER を取る gen_ai.span.kind 属性を通じて、そのビジネスセマンティクスを表現します。ネイティブエンジンのインストルメンテーションによって生成されたスパンにはこの属性がないため、ステージはスパン名から判断します。

エンジンやバージョンごとのフィールド名マッピング

セマンティクスが同じフィールドでも、エンジン、エンジンのバージョン、収集レイヤーによって名前が異なります。次の表では、同等のフィールド名をマッピングしています：

セマンティクス	フィールド名	報告元
入力トークン数	`gen_ai.usage.input_tokens`	vLLM と SGLang のエントリスパン
入力トークン数	`gen_ai.usage.prompt_tokens`	vLLM V0 と V1 の `llm_request` スパン、および SGLang のネイティブリクエストスパン
出力トークン数	`gen_ai.usage.output_tokens`	vLLM と SGLang のエントリスパン
出力トークン数	`gen_ai.usage.completion_tokens`	vLLM V0 と V1 の `llm_request` スパン、および SGLang のネイティブリクエストスパン
候補数	`gen_ai.request.choice.count`	vLLM と SGLang のエントリスパン
候補数	`gen_ai.request.n`	vLLM V0 と V1 の `llm_request` スパン、および SGLang のネイティブリクエストスパン
モデル名	`gen_ai.request.model`	vLLM と SGLang のエントリスパン
モデル名	`gen_ai.request.model_name`	vLLM V1 の `llm_request` スパン
モデル名	`model_name` (メトリックディメンション)	vLLM V1 のエンジン側メトリック
モデル名	`modelName` (メトリックディメンション)	vLLM の API レイヤーのトークンメトリックと SGLang のトークン消費メトリック
キャッシュから提供される入力トークン	`gen_ai.usage.cache_read.input_tokens`	vLLM V1 の `llm_request` スパンと SGLang のエントリスパン
キャッシュから提供される入力トークン	`gen_ai.usage.cached_tokens`	SGLang のネイティブリクエストスパン
最初のトークンまでの時間 (メトリック)	`genai_llm_first_token_seconds`	vLLM メトリック
最初のトークンまでの時間 (メトリック)	`gen_ai_server_time_to_first_token`	SGLang メトリック

vLLM スパン

スパンリスト

スパン名	生成元	説明
`chat {model name}`	OpenAI 互換 API レイヤー	チャット補完リクエストのエントリポイント、`/v1/chat/completions`。
`text_completion {model name}`	OpenAI 互換 API レイヤー	補完リクエストのエントリポイント、`/v1/completions`。
`embeddings {model name}`	OpenAI 互換 API レイヤー	埋め込みリクエストのエントリポイント。
`rerank {model name}`	OpenAI 互換 API レイヤー	リランクまたはスコアリクエストのエントリポイント。
`llm_request`	エンジン内部	エンジン内での 1 つのリクエストのライフサイクル全体。V0 と V1 の両方で生成されます。
`wait`	エンジン内部	リクエストがスケジューリングされるまでキューで待機する時間。V1 のみ。収集粒度が 1 以上の場合に収集されます。
`kv_transfer`	エンジン内部	リモートから KV キャッシュをプルする所要時間。`wait` の子スパンとしてネストされます。V1 のみ。収集粒度が 1 以上の場合に収集されます。
`prefill`	エンジン内部	プレフィルステージの所要時間。V1 のみ。収集粒度が 1 以上の場合に収集されます。
`decode`	エンジン内部	デコードステージの所要時間。V1 のみ。収集粒度が 1 以上の場合に収集されます。

kv_transfer は、wait と並列に配置されるのではなく、wait の内側にネストされます。vLLM がリモート KV キャッシュを待機している間、リクエストは WAITING_FOR_REMOTE_KVS 状態のままであるため、転送時間は待機時間に含まれます。

説明

実際のキューイング時間は、wait の所要時間から kv_transfer の所要時間を差し引いた値です。

PD 分離デプロイメントでは、Prefill ノードは prefill の子スパンのみを生成し、Decode ノードは decode の子スパンのみを生成します。

エントリスパン属性

エントリスパンは汎用の GenAI インストルメンテーションによって生成されます。属性定義は、他の大規模言語モデルフレームワークのインストルメンテーションと一貫しています。

属性	説明
`gen_ai.span.kind`	ビジネスセマンティクスの種別。`LLM`、`EMBEDDING`、または `RERANKER`。
`gen_ai.operation.name`	オペレーションの種別。`chat`、`text_completion`、`embeddings`、または `rerank`。
`gen_ai.request.model`	リクエストで指定されたモデル名。
`gen_ai.request.choice.count`	リクエストされた候補数。`n` パラメータに対応します。
`gen_ai.request.temperature`	サンプリング温度。
`gen_ai.request.top_p`	Top-P パラメータ。
`gen_ai.request.top_k`	Top-K パラメータ。
`gen_ai.request.max_tokens`	生成するトークンの最大数。
`gen_ai.request.is_stream`	リクエストがストリーミングリクエストかどうか。
`gen_ai.user.id`	リクエストに含まれる `user` フィールド。
`session.id`	ストリーミングシナリオにおけるリクエスト識別子。
`gen_ai.response.id`	レスポンス ID。
`gen_ai.response.model`	レスポンスで返されるモデル名。
`gen_ai.response.finish_reasons`	終了理由。
`gen_ai.usage.input_tokens`	入力トークン数。
`gen_ai.usage.output_tokens`	出力トークン数。
`gen_ai.usage.total_tokens`	合計トークン数。
`gen_ai.input.messages`	入力内容。コンテンツ収集スイッチによって制御されます。
`gen_ai.output.messages`	出力内容。コンテンツ収集スイッチによって制御されます。

`llm_request` スパン属性 (V0)

V0 エンジンの duration 属性の単位は秒です。

属性	説明
`gen_ai.request.id`	エンジン内のリクエスト ID。
`gen_ai.response.model`	レスポンスで返されるモデル名。
`gen_ai.request.temperature`	サンプリング温度。
`gen_ai.request.top_p`	Top-P パラメータ。
`gen_ai.request.max_tokens`	生成するトークンの最大数。
`gen_ai.request.n`	候補数。
`gen_ai.usage.num_sequences`	シーケンス数。
`gen_ai.usage.prompt_tokens`	入力トークン数。
`gen_ai.usage.completion_tokens`	出力トークン数。
`gen_ai.latency.e2e`	リクエストのエンドツーエンドの所要時間。
`gen_ai.latency.time_in_queue`	キューイング時間。
`gen_ai.latency.time_to_first_token`	最初のトークンまでの時間。
`gen_ai.latency.time_in_scheduler`	スケジューリング時間。エンジンがこのデータを提供する場合にのみ報告されます。
`gen_ai.latency.time_in_model_forward`	モデルフォワード計算の所要時間。エンジンがこのデータを提供する場合にのみ報告されます。
`gen_ai.latency.time_in_model_execute`	モデル実行の所要時間。フォワード計算、ワーカー間の同期、CPU-GPU 同期、およびサンプリングが含まれます。エンジンがこのデータを提供する場合にのみ報告されます。

`llm_request` スパン属性 (V1)

V1 エンジンの duration 属性の単位は ナノ秒 です。

属性	説明
`gen_ai.request.id`	エンジン内のリクエスト ID。
`gen_ai.request.model_name`	リクエストで指定されたモデル名。
`gen_ai.request.temperature`	サンプリング温度。
`gen_ai.request.top_p`	Top-P パラメータ。
`gen_ai.request.max_tokens`	生成するトークンの最大数。
`gen_ai.request.n`	候補数。
`gen_ai.usage.prompt_tokens`	入力トークン数。
`gen_ai.usage.completion_tokens`	出力トークン数。
`gen_ai.usage.cache_read.input_tokens`	再度プレフィルせずにキャッシュから提供される入力トークン数。ローカルのプレフィックスキャッシュヒットとリモート KV 再利用が含まれます。キャッシュヒット率を算出できるように、値が 0 の場合も報告されます。
`gen_ai.latency.e2e`	リクエストのエンドツーエンドの所要時間。
`gen_ai.latency.time_in_queue`	キューイング時間。
`gen_ai.latency.time_to_first_token`	最初のトークンまでの時間。
`gen_ai.latency.time_in_model_prefill`	プレフィルステージの所要時間。
`gen_ai.latency.time_in_model_decode`	デコードステージの所要時間。
`gen_ai.latency.time_in_model_inference`	推論ステージ (プレフィル + デコード) の合計所要時間。
`gen_ai.latency.time_in_tokenize`	フロントエンドプロセスにおけるプロンプトのトークン化時間。
`gen_ai.latency.time_in_detokenize`	累積の増分デトークン化時間。
`gen_ai.latency.time_in_kv_transfer`	リモート KV キャッシュ転送の合計所要時間。転送が発生した場合にのみ報告されます。
`gen_ai.request.preemption_count`	リクエストがプリエンプションされた回数。プリエンプションが発生した場合にのみ報告されます。
`gen_ai.engine.index`	EngineCore インスタンスのインデックス。マルチエンジンデプロイメントでエンジンを識別するために使用されます。
`gen_ai.pd_role`	PD 分離のロール。`producer` (Prefill ノード)、`consumer` (Decode ノード)、または `none` (PD 分離ではないデプロイメント)。

説明

PD 分離では、Prefill ノードでは Prefill の所要時間のみが正確です (time_in_model_decode は常に 0)。また、Decode ノードでは Decode の所要時間のみが正確です (time_in_model_prefill は常に 0)。vLLM はリクエストをプリエンプションしてもスケジューリングタイムスタンプをリセットしないため、Prefill、Decode、および Inference の所要時間には、プリエンプションによる停止時間がすでに含まれています。gen_ai.request.preemption_count は、このような所要時間のスパイクを説明する根拠になります。

ステージ子スパン属性

4 つの子スパン wait、kv_transfer、prefill、および decode には、いずれも gen_ai.request.id、gen_ai.request.model_name、gen_ai.engine.index、および gen_ai.pd_role が含まれます。kv_transfer には、次の追加属性が含まれます：

属性	説明
`gen_ai.kv_transfer.direction`	転送方向。値は `recv` で、Decode ノードが KV キャッシュをプルすることを意味します。
`gen_ai.kv_transfer.cached_tokens`	この転送でカバーされるトークン数。コネクタのリモート側で解決されたトークン数です。
`gen_ai.kv_transfer.failed`	このリクエストで、コネクタがロード失敗を報告したかどうか。

スパンイベント

収集粒度が 2 の場合、エンジンのスケジューリングの各反復ごとにスパンイベントが llm_request に追加されます。これにより、反復単位で実行プロセスを再構築できます。

イベント名	説明
`WAIT`	リクエストが待機状態に入ります。
`PREFILL`	1 回のプレフィル反復。
`DECODE`	1 回のデコード反復。
`PREEMPTED`	KV キャッシュブロックを解放するため、リクエストがプリエンプションされます。

イベント属性には gen_ai.engine.index と、トークンレベルの情報である gen_ai.token.ids、gen_ai.token.texts、gen_ai.token.count、および gen_ai.token.logprobs が含まれます。

説明

イベント数はリクエストの反復回数に比例し、スパンあたり 128 イベントという OpenTelemetry のデフォルト上限を容易に超える可能性があります。この場合、イベントは破棄されます。必要に応じて OTEL_SPAN_EVENT_COUNT_LIMIT を増やしてください。

vLLM メトリック

メトリックディメンション

vLLM のエンジン側メトリックには、次の共通ディメンションが含まれます：

ディメンション	説明
`callType`	常に `gen_ai` です。
`rpcType`	常に `2100` です。
`engine_index`	EngineCore インスタンスのインデックス。V1 のみ。
`model_name`	モデル名。V1 のみ。

gen_ai_vllm_request_success には、追加のディメンション finished_reason が含まれます。API レイヤーのトークンメトリックには、次のディメンションが含まれます：

ディメンション	説明
`callType`	常に `gen_ai` です。
`callKind`	常に `custom_entry` です。
`rpcType`	常に `2100` です。
`modelName`	モデル名。
`spanKind`	`LLM` または `EMBEDDING`。
`usageType`	`input` または `output`。

共通メトリック

V0 と V1 の両方のエンジンが、次のメトリックを報告します：

メトリック名	タイプ	単位	説明
`genai_llm_usage_tokens`	カウンター	Count	`usageType` で区別される入力トークンと出力トークンの使用量。
`vllm_iter_count`	カウンター	Times	エンジンのスケジューリングイテレーション数。
`gen_ai_vllm_request_success`	カウンター	Times	正常に完了したリクエスト数。
`genai_llm_first_token_seconds`	カウンター	Seconds	最初のトークンまでの時間の累積値。
`gen_ai_server_time_per_output_token`	カウンター	Seconds	出力トークンあたりの時間の累積値。
`gen_ai_server_request_duration`	カウンター	Seconds	リクエストのエンドツーエンド所要時間の累積値。

V0 メトリック

システムステータスのメトリックはゲージであり、収集時点の瞬時値を表します。

メトリック名	タイプ	単位	説明
`gpu_cache_usage_sys`	ゲージ	Ratio	GPU KV キャッシュの使用率。
`cpu_cache_usage_sys`	ゲージ	Ratio	CPU KV キャッシュの使用率。
`num_running_sys`	ゲージ	Count	実行中のシーケンス数。
`num_waiting_sys`	ゲージ	Count	待機中のシーケンス数。
`num_swapped_sys`	ゲージ	Count	スワップアウトされたシーケンス数。
`num_prompt_tokens_iter`	カウンター	Count	処理された入力トークンの累積数。
`num_generation_tokens_iter`	カウンター	Count	生成された出力トークンの累積数。
`num_tokens_iter`	カウンター	Count	処理されたトークンの累積合計数。
`num_preemption_iter`	カウンター	Times	プリエンプションの累積回数。

説明

ゲージメトリックは、エンジンのスケジューリング統計を実際に受け取るプロセスのみが報告します。純粋なフロントエンドプロセスなど、推論に関与しないプロセスは 0 の値を報告しません。これにより、マルチプロセスデプロイメントにおいて、意味のないゼロ値が連続してプロットされるのを回避できます。

V1 メトリック

メトリック名	タイプ	単位	説明
`gen_ai_vllm_num_requests_running`	ゲージ	Count	実行中のバッチに含まれるリクエスト数。
`gen_ai_vllm_num_requests_waiting`	ゲージ	Count	処理待ちのリクエスト数。
`gen_ai_vllm_kv_cache_usage_perc`	ゲージ	Ratio	KV キャッシュの使用率。範囲は [0, 1] です。
`gen_ai_vllm_prefix_cache_queries`	カウンター	Count	プレフィックスキャッシュでクエリされたトークン数。
`gen_ai_vllm_prefix_cache_hits`	カウンター	Count	プレフィックスキャッシュにヒットしたトークン数。
`gen_ai_vllm_num_preemptions`	カウンター	Times	エンジンのプリエンプション回数の累積値。
`gen_ai_vllm_prompt_tokens`	カウンター	Count	プレフィルによって処理されたトークン数。
`gen_ai_vllm_generation_tokens`	カウンター	Count	生成されたトークン数。
`gen_ai_vllm_request_params_n`	カウンター	Count	リクエストの `n` パラメータの累積値。
`gen_ai_vllm_request_params_max_tokens`	カウンター	Count	リクエストの `max_tokens` パラメータの累積値。
`gen_ai_vllm_request_queue_time_seconds`	カウンター	Seconds	WAITING ステージにおけるリクエストの所要時間の累積値。
`gen_ai_vllm_request_prefill_time_seconds`	カウンター	Seconds	プレフィルステージにおけるリクエストの所要時間の累積値。
`gen_ai_vllm_request_decode_time_seconds`	カウンター	Seconds	デコードステージにおけるリクエストの所要時間の累積値。
`gen_ai_vllm_request_inference_time_seconds`	カウンター	Seconds	推論フェーズ (RUNNING ステージ) におけるリクエストの所要時間の累積値。

プレフィックスキャッシュのヒット率は、gen_ai_vllm_prefix_cache_hits を gen_ai_vllm_prefix_cache_queries で割って算出します。

SGLang のスパン

スパンの構成と階層

SGLang シナリオのトレースは、エージェントが OpenAI 互換 API レイヤーで生成するエントリースパンと、ネイティブ SGLang インストルメンテーションによって生成されるスパンの 2 種類で構成されます。エージェントはエントリースパンのコンテキストをエンジンに送信するリクエストヘッダーに挿入するため、ネイティブスパンはエントリースパンの配下に配置され、1 つの完全なトレースを形成します。

chat {model name}                             ← エージェントのエントリー スパン
└─ Req {リクエスト ID の最初の 8 文字} ← ネイティブリクエストスパン、リクエストごとに 1 つ
   ├─ Tokenizer (host:… | pid:…)              ← ネイティブスレッドスパン、フロントエンドプロセス
   │  ├─ tokenize
   │  └─ api_server_dispatch
   └─ Scheduler [TP 0] (host:… | pid:…)       ← ネイティブスレッドスパン、スケジューラプロセス
      ├─ prefill_waiting
      ├─ prefill_forward
      │  └─ chunked_prefill
      └─ decode_forward
         └─ decode_loop

ネイティブインストルメンテーションは、リクエスト、スレッド、ステージの 3 階層構造を使用します。リクエストスパンは 1 つの完全なリクエストを表します。スレッドスパンは、リクエストの処理に関与する各プロセスまたはスレッドを表します。ステージスパンは、そのスレッド内の 1 つの処理ロジックを表します。テンソル並列 (TP)、パイプライン並列 (PP)、またはデータ並列 (DP) を使用するマルチ GPU デプロイメントでは、1 つのリクエストに複数のスレッドスパンが存在し、スケジューラプロセスごとに 1 つずつ対応します。同じスレッド内の連続するステージスパン間、およびプロセスをまたぐステージスパン間にはスパンリンクが確立され、これにより実行順序を再構築できます。スパンリンクは親子関係ではありません。

エントリースパンリスト

エージェントのエントリーインストルメンテーションは、リクエストごとに正確に 1 つのスパンを生成し、子スパンは生成しません。リクエスト内のステージの内訳は、ネイティブインストルメンテーションによって提供されます。

スパン名	説明
`chat {model name}`	チャット補完リクエスト、`/v1/chat/completions`。
`text_completion {model name}`	補完リクエスト、`/v1/completions`。

エントリースパンの属性

リクエスト側の属性：

属性	説明
`gen_ai.span.kind`	常に `LLM`。
`gen_ai.operation.name`	`chat` または `text_completion`。
`gen_ai.request.model`	リクエストで指定されたモデル名。
`gen_ai.request.id`	リクエストID。チャットストリーミングシナリオで報告されます。
`gen_ai.request.is_stream`	リクエストがストリーミングリクエストであるかどうかを示します。
`gen_ai.request.temperature`	サンプリング温度。
`gen_ai.request.top_p`	Top-P パラメータ。
`gen_ai.request.top_k`	Top-K パラメータ。
`gen_ai.request.max_tokens`	生成するトークンの最大数。
`gen_ai.request.choice.count`	候補数。

レスポンス側の属性：

属性	説明
`gen_ai.response.id`	レスポンスID。
`gen_ai.response.model`	レスポンスで返されるモデル名。非ストリーミングシナリオで報告されます。
`gen_ai.response.finish_reasons`	終了理由。
`gen_ai.usage.input_tokens`	入力トークン数。
`gen_ai.usage.output_tokens`	出力トークン数。
`gen_ai.usage.total_tokens`	総トークン数。
`gen_ai.usage.cache_read.input_tokens`	キャッシュから提供された入力トークン数。
`gen_ai.latency.e2e`	リクエストのエンドツーエンドの期間 (秒)。
`gen_ai.response.tokens_streamed`	ストリーミングシナリオにおける出力トークンの推定数で、ストリーミング増分数にエンジンの `stream_interval` を乗じて計算されます。サーバーが使用量を返さない場合、`gen_ai.usage.output_tokens` を補完します。
`gen_ai.input.messages`	入力コンテンツ。コンテンツ収集スイッチによって制御されます。
`gen_ai.output.messages`	出力コンテンツ。コンテンツ収集スイッチによって制御されます。

ツール呼び出し属性 (チャットストリーミングシナリオ)：

属性	説明
`gen_ai.request.has_tool_calls`	リクエストがツールを宣言しているかどうかを示します。
`gen_ai.request.tool_call_detected`	レスポンスでツール呼び出しが検出されたかどうかを示します。
`gen_ai.request.tool_calls_count`	検出されたツール呼び出しの数。
`gen_ai.completions.{i}.tool_calls.{j}.name`	候補 `i` におけるツール呼び出し `j` の名前。
`gen_ai.completions.{i}.tool_calls.{j}.arguments`	そのツール呼び出しの引数。

エントリースパンはカスタムスパンイベントを生成しません。コンテンツ収集ポリシーが event に設定されている場合、入力および出力コンテンツはスパン属性に書き込まれる代わりに、gen_ai.client.inference.operation.details ログイベントとして報告されます。

ネイティブインストルメンテーションの有効化と収集レベル

エージェントはエンジン起動時に SGLang のネイティブトレーススイッチをオンにするため、手動で --enable-trace を追加する必要はありません。ネイティブスパンはエージェントによって登録されたグローバルな TracerProvider を通じて報告されるため、--otlp-traces-endpoint を設定する必要もなく、ネイティブスパンはエントリースパンと同じアプリケーションに属します。

ネイティブインストルメンテーションは、各ステージスパンに対して収集レベルを定義し、これは SGLANG_TRACE_LEVEL 環境変数によって制御されます。デフォルト値の 3 では、レベル 1 から 3 のすべてのステージスパンが報告されます。値を小さくすると、より重要なステージのみが保持され、0 にするとネイティブインストルメンテーションが無効になります。エンジンは、実行時に動的に調整するための /set_trace_level?level=N 操作も提供します。ネイティブスパンの数はデプロイメントの規模とともに増加し、マルチ GPU デプロイメントでは 1 つのリクエストで 10 を超えるスパンが生成されます。トレースデータ量が多い場合は、まず SGLANG_TRACE_LEVEL を下げてください。

リクエストスパンとスレッドスパン

リクエストスパンは、ネイティブインストルメンテーションのルートスパンです。これはフロントエンドプロセスで作成および終了され、その名前は {role} Req {リクエスト ID の最初の 8 文字} の形式に従います。ロールは、PD 分離下では prefill または decode であり、非 PD デプロイメントでは空です。

属性	説明
`rid`	リクエストID。
`module`	常に `sglang::request`。
`bootstrap_room`	PD 分離下でのリクエスト相関識別子。16 進数の文字列で、PD シナリオでのみ報告されます。
`gen_ai.request.id`	リクエストID。
`gen_ai.request.temperature`	サンプリング温度。
`gen_ai.request.top_p`	Top-P パラメータ。
`gen_ai.request.top_k`	Top-K パラメータ。
`gen_ai.request.n`	候補数。
`gen_ai.request.max_tokens`	生成するトークンの最大数。
`gen_ai.response.model`	サーバーで設定されたモデル名。
`gen_ai.response.finish_reasons`	終了理由 (JSON 配列文字列)。
`gen_ai.usage.prompt_tokens`	入力トークン数。
`gen_ai.usage.completion_tokens`	出力トークン数。埋め込みリクエスト以外のリクエストで報告されます。
`gen_ai.usage.cached_tokens`	キャッシュから提供された入力トークン数。
`gen_ai.latency.time_to_first_token`	最初のトークンまでの時間。
`gen_ai.latency.e2e`	リクエストのエンドツーエンドの期間。
`gen_ai.latency.time_in_model_prefill`	リクエストディスパッチの完了から最初のトークンまでの期間。
`gen_ai.latency.time_in_model_decode`	最初のトークンからリクエストの終了までの期間。
`gen_ai.latency.time_in_model_inference`	リクエストディスパッチの完了からリクエストの終了までの期間。

すべての期間属性の単位は秒です。リクエストスパンの属性は、リクエストが正常に終了した場合にのみ記録されます。

説明

期間属性はフロントエンドプロセスから見た時間差であり、スケジューラ内部の実際の順伝播計算期間と完全に等しいわけではありません。後者については、ステージスパンの実際の期間をご参照ください。

スレッドスパンの名前は、{thread label} [TP n] [PP n] [DP n] (host:{host identifier} | pid:{thread ID}) の形式に従います。ランク情報は、対応する値が存在する場合にのみ追加されます。スレッドラベルは Tokenizer、MultiTokenizer-{number}、DP Controller、または Scheduler であり、PD 分離下では Prefill または Decode プレフィックスが付きます。デトークナイザープロセスにはネイティブインストルメンテーションがないため、対応するスレッドスパンは表示されません。

属性	説明
`host_id`	ホストの一意の識別子。異なるノード上で同じ PID を共有するプロセスを区別します。
`pid`	スレッドID。
`thread_label`	スレッドラベル。
`tp_rank`	テンソル並列ランク。存在する場合に報告されます。
`pp_rank`	パイプライン並列ランク。存在する場合に報告されます。
`dp_rank`	データ並列ランク。存在する場合に報告されます。

説明

リクエストが異常終了した場合、エラーステータスと終了理由はスレッドスパンに記録されます。そのステータスは ERROR に設定され、終了理由に関連する属性が追加されます。リクエストスパン自体はエラーとしてマークされません。失敗したリクエストを調査する際は、スレッドスパンのステータスを確認してください。

ステージスパンリスト

以下の表では、「レベル」列が SGLANG_TRACE_LEVEL に対応します。レベル値が設定値より大きいスパンは生成されません。

共通ステージ：

スパン名	レベル	生成プロセス	説明
`tokenize`	1	フロントエンド	プロンプトのトークン化期間。
`api_server_dispatch`	2	フロントエンド	フロントエンドからスケジューラへリクエストをディスパッチする期間。
`dpc_dispatch`	2	DP Controller	データ並列コントローラがリクエストをディスパッチする期間。DP が有効な場合にのみ生成されます。
`request_process`	2	スケジューラ	リクエストがスケジューラに入ってから待機キューに入るまでの処理期間。非 PD 分離デプロイメントでのみ。
`prefill_waiting`	1	スケジューラ	リクエストがプレフィルのためにスケジュールされるまでキューで待機する時間。
`prefill_forward`	1	スケジューラ	プレフィルの順伝播計算の期間。
`chunked_prefill`	3	スケジューラ	1 つのチャンクのプレフィル期間。`prefill_forward` の下にネストされます。
`decode_waiting`	1	スケジューラ	プレフィルの完了から最初のデコードのスケジューリングまでの待機時間。
`decode_forward`	1	スケジューラ	デコードステージ全体の期間。
`decode_loop`	3	スケジューラ	1 回のデコードイテレーションの期間。`decode_forward` の下にネストされます。

説明

decode_forward には独立した終了点がありません。リクエストが終了する際にスレッドと一緒に閉じられるため、その期間は最初のデコードスケジューリングからリクエストの終了までの全区間をカバーします。

投機的デコードステージ：投機的デコードが有効な場合に生成され、フォワードスパンの下にネストされます。

スパン名	レベル	説明
`spec_draft`	2	ドラフトモデルが候補トークンを生成する期間。
`spec_verify`	2	ターゲットモデルがドラフトトークンを検証する期間。
`spec_draft_extend`	3	ドラフトモデルの拡張ステージの期間。

パイプライン並列ステージ：

スパン名	レベル	説明
`run_batch_cpu`	4	パイプライン並列下での CPU 側バッチ処理の期間。レベル 4 はデフォルト値の 3 より高いため、このスパンは明示的に `SGLANG_TRACE_LEVEL=4` を設定した場合にのみ生成されます。

PD 分離デプロイメントの追加ステージ (プレフィルノード)：

スパン名	レベル	説明
`prefill_prepare`	1	プレフィルノードがリクエストを受信した後の準備期間。
`prefill_bootstrap`	1	デコードノードとの転送接続を確立する期間。
`prefill_transfer_kv_cache`	1	KV キャッシュをデコードノードに転送する期間。

PD 分離デプロイメントの追加ステージ (デコードノード)：

スパン名	レベル	説明
`decode_prepare`	1	デコードノードがリクエストを受信した後の準備期間。
`decode_bootstrap`	1	プレフィルノードとの転送接続を確立する期間。
`decode_transferred`	1	KV キャッシュ転送が完了するのを待つ期間。
`fake_output`	3	デコードノードがプレフィルステージの出力を完了するまでの期間。

説明

PD 分離下では、プレフィルとデコードはそれぞれ独立したリクエストスパンを持ち、2 つの独立したトレースを形成します。これら 2 つのトレースは、リクエストスパン上の bootstrap_room 属性を介して 1 つのリクエストとして関連付けられます。PD 分離デプロイメントのデコードノードでは、decode_waiting の意味が変わり、KV キャッシュ転送の完了から順伝播計算の開始までのキューイングを指すようになります。これは非 PD デプロイメントでの意味とは異なります。

ステージスパンの属性とスパンイベント

ステージスパンは、デフォルトではカスタム属性を持ちませんが、以下の 3 つの例外があります。

スパン名	属性	説明
`decode_loop`	`decode_ct`	現在のデコードイテレーション番号。
`spec_verify`	`num_correct_drafts`	この検証をパスしたドラフトトークンの数。 `accepted_tokens` は同じ値を持つ互換エイリアスです。
`run_batch_cpu`	`pp_mb_id`	パイプライン並列のマイクロバッチ番号。

ネイティブインストルメンテーションは 2 種類のスパンイベントを生成します。

イベント名	レベル	属性	説明
`retract`	1	なし	リソース不足によりリクエストがロールバックされ、再キューイングされたときに記録されます。
`schedule`	3	`bid`、`batch_size`、`forward_mode`	リクエストがバッチに配置されたときに記録されます。`bid` はバッチ識別子で、`forward_mode` は `decode`、`prefill`、または `prebuilt` の値を取ります。

説明

イベントは、その発生時刻が含まれる期間を持つステージスパンにタイムスタンプによって関連付けられます。すべてのステージ期間外にあるイベントはスレッドスパンにアタッチされるため、同じ名前のイベントがリクエストごとに異なる位置にアタッチされることがあります。

SGLang のメトリック

メトリックディメンション

エンジン側のメトリック (スケジューラおよびフロントエンドの統計) に含まれるディメンション：

ディメンション	説明
`callType`	常に `gen_ai` です。
`callKind`	常に `custom_entry` です。
`rpcType`	常に `2100` です。

トークン消費量メトリックは、追加のディメンション modelName、spanKind、および usageType (input または output) を持ちます。

メトリックリスト

メトリック名	タイプ	単位	説明
`genai_llm_usage_tokens`	カウンター	Count	`usageType` によって区別される、入力および出力トークンの消費量です。
`sglang_num_running_reqs`	カウンター	Count	実行中のリクエスト数のスナップショットです。
`sglang_num_queue_reqs`	カウンター	Count	キュー内のリクエスト数のスナップショットです。
`sglang_num_used_tokens`	カウンター	Count	現在使用中のトークン数のスナップショットです。
`sglang_token_usage`	カウンター	比率	KV キャッシュのトークン使用量のスナップショットです。
`sglang_gen_throughput`	カウンター	Tokens/s	生成スループットのスナップショットです。
`gen_ai_sglang_cache_hit_rate`	カウンター	比率	キャッシュヒット率のスナップショットです。エンジンがこのフィールドを提供する場合にのみ報告されます。
`sglang_spec_accept_length`	カウンター	Count	投機的デコーディングの受理長です。
`sglang_log_count`	カウンター	Times	統計レポートの数です。これは、先行するスナップショットメトリックの平均を計算するために使用されます。
`prompt_tokens_total`	カウンター	Count	入力トークンの累積数です。
`generation_tokens_total`	カウンター	Count	出力トークンの累積数です。
`gen_ai_sglang_cached_tokens_total`	カウンター	Count	キャッシュから提供された入力トークンの累積数です。
`num_requests_total`	カウンター	Times	リクエストの累積数です。
`gen_ai_server_time_to_first_token`	カウンター	Seconds	最初のトークンまでの累積時間です。
`gen_ai_server_time_per_output_token`	カウンター	Seconds	出力トークンあたりの累積時間です。
`sglang_inter_token_latency_seconds`	カウンター	Seconds	トークン間レイテンシーの累計です。
`gen_ai_server_request_duration`	カウンター	Seconds	リクエストのエンドツーエンドの期間の累計です。

説明

SGLang のシステムステータスメトリックはカウンターとして報告されますが、意味的には各値は 1 つの統計期間の瞬間的なスナップショットです。ダッシュボードでは、累積値を直接読み取るのではなく、sglang_log_count と共に期間内で平均化してください。

gen_ai_server_time_per_output_token は、エンドツーエンドの期間を出力トークン数で割ったものであるため、平均値です。トークン間の実際の時間間隔を観測するには、sglang_inter_token_latency_seconds を使用してください。

共通のスパン規約

エンジンやバージョンごとのフィールド名マッピング

vLLM スパン

スパンリスト

エントリスパン属性

llm_request スパン属性 (V0)

llm_request スパン属性 (V1)

ステージ子スパン属性

スパンイベント

vLLM メトリック

メトリックディメンション

共通メトリック

V0 メトリック

V1 メトリック

SGLang のスパン

スパンの構成と階層

エントリー スパンリスト

エントリー スパンの属性

ネイティブインストルメンテーションの有効化と収集レベル

リクエストスパンとスレッドスパン

ステージスパンリスト

ステージスパンの属性とスパンイベント

SGLang のメトリック

メトリックディメンション

メトリックリスト

`llm_request` スパン属性 (V0)

`llm_request` スパン属性 (V1)

エントリースパンリスト

エントリースパンの属性