vLLM/SGLang 採集配置說明 - Application Real-Time Monitoring Service

推理服務上線後，採集範圍、調用鏈粒度和日誌行為往往需要隨排查進度反覆調整：定位問題時要開啟更細的粒度，涉及敏感性資料或日誌量過大時又要及時收斂。接入 ARMS Python 探針後，vLLM/SGLang 的這些採集行為均可在CloudMonitor 2.0 控制台動態調整，多數修改無需重啟推理引擎。本文按控制台上的四個面板逐項說明每個開關的含義、預設值與生效條件，並給出對應的環境變數，便於在應用啟動前靜態指定採集行為。

進入採集配置頁面

本文適用於已通過 ARMS Python 探針接入 vLLM/SGLang 推理引擎的應用，接入流程請參見對 vLLM/SGLang 推理引擎進行可觀測。

登入CloudMonitor 2.0 控制台。
選擇應用可觀測 > 应用监控，單擊目標推理服務名稱。
進入應用配置頁簽，按需調整下列面板中的開關。
與推理引擎相關的配置分布在以下四個面板：探針開關設定、AI 應用採集配置、vLLM 推理引擎配置、SGLang 推理引擎配置。下文表格的“預設值”指引擎或探針自身的預設取值：控制台不下發該項時，探針讀取環境變數的取值；環境變數也未設定時，使用引擎或探針自身的預設值。

探針開關設定

LLM（大語言模型）服務分組下有 vllm-plugin 和 sglang-plugin 兩個勾選項，控制探針啟動時是否載入對應外掛程式。取消勾選後探針不再插樁該引擎，調用鏈和指標都不會產生。此開關在探針載入階段讀取，修改後需要重啟應用才會生效；如需臨時停止採集，使用下文各面板的採集開關即可，無需重啟。

AI 應用採集配置

開關	預設值	說明
是否採集大模型輸入輸出內容	開啟	是否將請求的 Prompt 與模型輸出記錄到可觀測資料中。涉及敏感性資料時可關閉。
大模型輸入輸出內容欄位長度限制	8192	單條輸入或輸出內容採集的最大字元數，超出部分截斷。
大模型輸入輸出內容採集策略	記錄到 Span 屬性	採集內容的寫入位置，可選記錄到 Span 屬性（隨調用鏈查看）或記錄到日誌事件（內容體積較大時更合適）。
是否採集多模態資料	關閉	僅對用戶端架構埋點（LangChain、LiteLLM、DashScope、Google ADK 等）生效，vLLM/SGLang 引擎側插樁不消費該開關。

關閉輸入輸出內容採集後，vLLM 側的 chat {model}、text_completion {model} 入口 Span 整體不再產生，引擎內部的 llm_request 及其子 Span 不受影響；embeddings {model}、rerank {model} 入口 Span 同樣不受影響。是否為這部分內容註冊埋點在探針啟動時就已確定，因此該開關對入口 Span 的影響需要重啟引擎後才會改變。

vLLM 推理引擎配置

開關	預設值	說明
vLLM 是否採集指標	探針預設開啟	探針是否從推理引擎讀取指標。關閉後探針不再採集；採集到之後能否上報，還取決於自訂配置頁的是否上報指標開關。
vLLM 採集粒度	探針預設 1	調用鏈採集的詳細程度。`0`：只產生 `llm_request` 請求級 Span；`1`：額外產生 `wait`、`prefill`、`decode`、`kv_transfer` 階段子 Span；`2`：再按調度迭代逐次記錄 Span Event 並採集 token 級明細。
vLLM 請求日誌	引擎預設關閉	列印請求接收與生命週期日誌（Received request、Added request、aborted、failed）。需 vLLM 0.10.1 及以上版本，對新請求生效。
vLLM 迭代詳情日誌	引擎預設關閉	EngineCore 每次迭代列印上下文階段與產生階段的請求數、token 數與迭代耗時，用於排查批次打不滿、請求饑餓等調度異常。需 vLLM 0.14.0 及以上版本。
vLLM 日誌關聯 TraceId	探針預設關閉	向 vLLM 日誌首碼注入 TraceId 與 SpanId，用於日誌與調用鏈互查。
vLLM 記錄層級	引擎預設 INFO	動態調整 vLLM 記錄層級，同時調整 Logger 與其 Handler，避免 DEBUG 日誌被 Handler 攔截。

說明

採集粒度設定為 2 時，探針會強製為請求開啟 logprobs 計算以擷取 token 級明細，改變引擎的實際計算行為，並帶來明顯的效能與資料量開銷；單個 Span 的 Event 數量與迭代次數成正比，可能超過 OpenTelemetry 預設的 128 條上限而被丟棄，該上限由 OTEL_SPAN_EVENT_COUNT_LIMIT 控制。建議僅在排查問題期間臨時開啟採集粒度 2。迭代詳情日誌逐迭代全量輸出且不做採樣，高吞吐情境下日誌量很大，排查完成後建議及時關閉。

SGLang 推理引擎配置

開關	預設值	說明
SGLang 是否採集指標	開啟	探針是否從推理引擎讀取指標。開啟時探針會補齊引擎的請求級指標統計（TTFT、token 間延遲、token 總量、端到端耗時），無需為此重啟引擎並添加 `--enable-metrics` 啟動參數。
SGLang 採集粒度	3 + 複合階段	SGLang 原生 OTel 埋點的 Span 樹深度，數值越大越詳細。僅在引擎的原生 tracing 開啟時有效：探針會在引擎啟動時自動開啟該開關，無需手動添加 `--enable-trace`，要求 SGLang v0.5.3 及以上版本；版本更低時只有入口 Span，該配置不生效。修改後只對新進入的請求生效。
SGLang 請求日誌	引擎預設關閉	動態開關 TokenizerManager 的請求日誌。
SGLang 請求日誌詳細度	引擎預設 2	請求日誌列印的詳細程度，數值越大內容越多。
SGLang 記錄層級	引擎預設 INFO	動態調整 `sglang` Logger 的記錄層級。

上述開關在首次覆蓋時會記錄引擎的原始取值，配置項從控制台移除後自動回復。關閉指標採集只停止探針自身的上報，不會關閉引擎原生的 Prometheus 指標。

附錄：對應的環境變數

應用啟動前如需靜態指定採集行為，可使用下表的環境變數。控制台配置優先於環境變數，控制台未下發該項時才回落到環境變數。

控制台開關	環境變數	控制台配置鍵
外掛程式總開關 (vLLM)	`OTEL_INSTRUMENTATION_VLLM_ENABLED`	`otel.instrumentation.vllm.enabled`
外掛程式總開關 (SGLang)	`SGLANG_INSTRUMENTATION_ENABLED`	`otel.instrumentation.sglang.enabled`
是否採集大模型輸入輸出內容	`OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`	`otel.instrumentation.genai.capture-message-content`
大模型輸入輸出內容欄位長度限制	`OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_MAX_LENGTH`	`otel.instrumentation.genai.message-content.max-length`
大模型輸入輸出內容採集策略	`OTEL_INSTRUMENTATION_GENAI_MESSAGE_CONTENT_CAPTURE_STRATEGY`	`otel.instrumentation.genai.message-content.capture-strategy`
vLLM 是否採集指標	`OTEL_INSTRUMENTATION_VLLM_METRICS_ENABLED`	`otel.instrumentation.vllm.metrics.enabled`
vLLM 採集粒度	`OTEL_INSTRUMENTATION_VLLM_TRACING_LEVEL`	`otel.instrumentation.vllm.tracing.level`
vLLM 請求日誌	—	`apsara.apm.inference.vllm.log_requests.enabled`
vLLM 迭代詳情日誌	—	`apsara.apm.inference.vllm.log_iteration_details.enabled`
vLLM 日誌關聯 TraceId	—	`apsara.apm.inference.vllm.log_trace_context.enabled`
vLLM 記錄層級	—	`apsara.apm.inference.vllm.logging.level`
SGLang 是否採集指標	`OTEL_INSTRUMENTATION_SGLANG_METRICS_ENABLED`	`otel.instrumentation.sglang.metrics.enabled`
SGLang 採集粒度	—	`otel.instrumentation.sglang.tracing.level`
SGLang 請求日誌	—	`apsara.apm.inference.sglang.log_requests.enabled`
SGLang 請求日誌詳細度	—	`apsara.apm.inference.sglang.log_requests.level`
SGLang 記錄層級	—	`apsara.apm.inference.sglang.logging.level`