跳转到正文

查看指标与检索日志

本文目录

适用场景:查看集群和部署的 GPU 指标、排查某个实例为什么起不来或报错、按关键字检索历史日志。

完成后,能从异常时间段或请求 ID 找到相关副本,结合指标、事件和日志确定下一步排查方向。

前置条件:能登录控制台;查看实时节点指标时节点已接入且在线。查看实例历史日志时,实例需已创建并产生过日志;查看网关请求时,需有经过 /v1 或 Playground 的调用。

1. 看概览与指标

  1. 打开侧边栏监控中心,查看 GPU 利用率、显存、温度和实例状态,并选择问题发生的时间范围。
  2. 先看顶部「数据截至 …」。最近 30 秒没有新样本时会显示「数据滞后」,此时图中是最后一次样本; 「暂无样本」表示还未收到数据。节点离线时先恢复连接,不能用旧值判断当前负载。
  3. 进入相关服务的监控页,查看请求对账、延迟、吞吐和运行请求。网卡、RDMA 端口与角色流量的含义见网络指标参考。

服务或节点删除后,原始样本仍保留到期(默认 72 小时)。监控中心的服务列表、显存条只显示现有的服务和节点;指标浏览器按节点或部署分组时,已删除的仍按删除时的名字显示并标「已删除」。打开已删除服务的监控页,会提示它已删除,并提供到用量分析的链接,那里保留它的历史用量、服务质量和卡时。

页面右上角选时间范围:15 分钟到 7 天几个预设都以「现在」为终点,并按「跟随最新」定时刷新;也可以用日期选择器选任意一段(最长 30 天、不能晚于现在,受数据保留里指标原始样本的保留时长限制)。选了自定义时间段时页面不再刷新,图表、请求分布、延迟拆解和信号都按这一段计算,服务列表、副本和健康检查仍显示当前状态,页面上有一行文字说明。这个选择记在地址栏(?from=…&to=…),可以直接分享。更长期的趋势(按小时、按天的 Token 用量、服务质量、GPU 利用和卡时)在「用量分析」页看,见查看用量分析。

部署指标有两个来源,比较不同引擎前先确认口径:

  • 引擎:agent 采集实例的指标端点,按模板映射为平台指标。vLLM / SGLang 有内置映射;未声明映射的 callable 引擎导出 vllm: / sglang: 前缀的指标时自动识别,其他引擎需声明指标映射。
  • 网关:测量经过网关的请求耗时和在途数,并读取回复 usage 中的 token 数。即使引擎不提供指标端点,也能有网关统计;直接访问实例的请求不计入这些统计。
看到的指标如何理解或继续处理
TTFT、端到端、TPOT、输入 / 输出 token 吞吐、运行请求优先使用引擎值,否则使用可用的网关统计,界面不标注来源;两边都缺少时没有数值。网关的运行请求是包含排队的在途数,不能直接等同于引擎执行数
排队 / Prefill / Decode 时长没有引擎指标时,网关只能汇总回复里实际自报的逐请求统计;缺少字段就无法拆出对应阶段
KV 使用率、排队请求、抢占只能由引擎提供。缺失时服务监控页会注明,不能将其当作 0
请求对账(近 5 分钟)比较网关转发数与引擎完成数;缺口持续超过在途数时标红。到后面的请求视图与实例日志核对失败,不凭红字直接确定根因。引擎不报完成计数时卡片不显示

网关指标中的 TTFT 从请求交给实例计到首个生成 token(包括思考),端到端计到回复结束,包含实例排队与网络耗时;它们与引擎内部计时不同。

网关 TPOT 是首个生成 token 到最后一个文本块的时间除以输出 token 数减一,包含网络抖动;需要 usage 中的输出计数且至少有两个 token,不能把流式块数当作 token 数。

TPOT 与阶段时长的网关回退只为内置映射缺少对应指标的引擎生成;关闭 vLLM / SGLang 的指标采集不会因此额外生成这些回退,缺数据时仍需恢复引擎采集。

没有引擎指标时,部署详情的指标面板会改为显示可用的网关统计。完整指标名、来源和单位见推理指标词表。

服务页的「KV Cache」图按副本画两条线:左轴是使用率,右轴是前缀缓存命中率,都是 0–100%。命中率对导出命中/查询计数的引擎(vLLM)按每个时间点内的命中数除以查询数算,对只报瞬时命中率的引擎(SGLang)直接用它;某个时间点没有查询时这一点留空,不画成 0。

2. 看请求视图与请求分布

这里记录经过 /v1 与 Playground 的请求;直接调用实例端口的请求不在网关请求视图内。 服务页顶部常驻延迟拆解、健康、阶段条和泳道散点,下方是概览、实时请求和历史请求。

查找已结束的请求

按手头的信息选择入口:

  • 已有请求 ID 或 trace id:在监控中心右上角搜索框粘贴 ID。trace id 为 32 位十六进制,可跨部署列出同一 trace 的请求。 网关生成的 trace id 可直接定位时间;其他 ID 默认查最近 1 小时,可扩大到最近 24 小时。 请求所属的部署已删除时,按删除时的名字显示并标「已删除」。
  • 还不知道具体请求:进入服务页的历史请求,按时间倒序查找。选择时间范围,按结果(正常完成、长度截断、客户端退出、连接中断、出错)和端到端时间筛选。 每页 50 行,用上一页 / 下一页继续查找;底部请求总数不受筛选和列表抽样影响。

找到请求后,点击请求行或聚焦后按回车,核对调用方、落到的副本、token 数、结束原因和阶段时间线。 可复制请求 ID、trace id;配置了 Trace 链接后,可点在追踪系统中打开。

历史请求和实时请求均可按 API key 和副本筛选。每行标出副本序号与节点,色条按该请求自身总时长表示各阶段占比; 悬停或用键盘聚焦可查看阶段耗时、Prefill / Decode 速度、token 数与结束原因。

查看实时请求与卡顿

请求还没结束时,打开实时请求。列表按等首字最久、思考中、输出中排序,每行显示请求体大小、已收到的块数和已过时间。 每 2 秒刷新,可暂停,默认显示 20 行,最多显示 200 行。

请求结束前引擎尚未返回排队、Prefill 统计,首字之前合并显示为等首字。发现异常请求时,记录副本和时间,继续查看该实例的事件与日志。

阶段条每 2 秒更新当前等首字、思考中、输出中的请求数,同时列出等首字最久的时间与卡顿数。 思考或输出超过 2 秒没有新块时标为卡顿。

泳道散点按这三个阶段分泳道,横轴是已过时间(对数刻度,至少到 60 秒);红色描边表示卡顿,悬停可看调用方、副本、块数与静默时长。 等首字泳道右侧聚集说明很多请求仍在等待,孤立的长耗时点值得单独检查,但不能仅凭位置确定排队或故障原因。

散点最多显示 500 个,优先显示等首字最久的请求;数量上限不代表其余请求不存在。

查看服务趋势与分布

需要判断整个服务的趋势时,在服务页概览查看分布;顶部的延迟拆解与健康也可结合判断。

  • 输入输出分布:按输入 token × 输出 token 计数,两轴按 2 的幂分档,用于判断长输入短输出还是短输入长输出。 监控中心看全集群,服务页看当前部署,均使用所选时间范围内结束的请求。
  • 非缓存输入 token × 首 token 时间:观察长输入与首字变慢是否同时发生。未命中输入少但首字慢时,再检查排队、预处理和网络;分布本身不能证明原因。 卡片标明 usage 和缓存上报覆盖数。

查看健康和副本状态

已开启健康检查时,健康卡片显示最近结果、耗时、回复副本和最近 10 次检查。绿为正常、橙为超时、红为失败,旧结果在左; 悬停查看每次时间与失败原因。平均耗时只算阈值内成功回复。

未开启时,可从卡片进入部署详情开启。每分钟检查一次,结果仅留在 server 内存,重启后等待新结果。 卡片还显示就绪 / 期望副本数与各副本状态。

解读端到端延迟

端到端延迟拆解统计所选时间范围内的完整回复(正常完成或长度截断),用于查看时间主要花在网关、等待、Prefill、思考、回答还是收尾。 悬停或聚焦某段查看占比、p50 / p95 与速度;缺少引擎自报时,无法拆开的部分显示为等首字。

这里的端到端从网关收到请求计到响应结束,包含网关处理;与第 1 节从交给实例开始计时的网关指标不是同一起点。 首个 token 取首个思考与首个回答中较早的那个,最后一块只指带生成文本的块,不含结束或 usage 块。

这些生成时间点只在流式回复中可观察;非流式回复若报齐引擎排队、Prefill、Decode,也可按自报拆分,不能把未观察到的首字或思考时间当作 0。

各阶段表示什么

下表以流式回复为例:

阶段含义与判断条件
网关收到请求到交给副本的时间;PD 顺序交接另列的 Prefill 时间不重复计入
引擎预处理引擎报了排队和 Prefill 后,首字前等待扣除这两项的剩余时间,包括模板处理、分词、进入调度前等待及首 token 返回的网络时间。并发高或单步计算长时可能增大,不等于纯 CPU 处理时间
引擎排队 / Prefill / 等首字排队和 Prefill 取引擎自报。只报 Prefill 时,Prefill 单列,其余合为等首字;未报 Prefill 时整段等待合为等首字,不能据此当作纯排队
思考 / 正式回答思考从首个思考块到首个回答块(无回答时到最后一块);回答从首个回答块到最后一块
引擎后处理最后一个文本块到响应结束,包括结束块、usage、[DONE] 及网关写回客户端;客户端读得慢也算在这里,不能只归因于引擎

PD 模式与旧记录

两个 vLLM PD 模式顺序交接时,网关之后多出一段 Prefill,表示网关等 prefill 实例的时间(单条请求里叫 PD Prefill)。 decode 自报排队显示为 KV 传输·排队,包含等待远端 KV;decode 的 Prefill 显示为 首 token 重算,占端到端平均不超过 1% 时不画出。

旧记录若未单独记录网关耗时,不能用它与新记录的引擎预处理直接比较。

平均值、分位数与速度

各段平均按所有完整回复计算,没有该阶段的回复按 0 计,所以各段之和等于端到端平均;这不表示未上报的引擎阶段实际耗时为 0。 顶部显示端到端平均及 p50 / p95;阶段分位数只统计出现该阶段的请求,分档误差约 10%。汇总使用全部请求,不受请求日志抽样影响。

速度按有对应 token 数和时长的请求,累加 token 后除以累加时长:

  • Prefill:使用未命中缓存的输入与引擎 Prefill 时间;顺序 PD 用 P 实例的自报时间。
  • 思考:使用思考 token 与思考阶段时长。
  • 回答:使用输出减思考 token 与回答阶段时长;usage 没有思考计数时,只纳入没有思考阶段的回复。
  • Decode:优先用引擎自报耗时,否则用首个到最后一个生成 token 的间隔及输出 token 数减一。

缺少 token 或相应阶段时无法计算速度。字段与完整拆分规则见请求时间线与阶段拆分。

请求查不到或缺少数据

没有 token 分布或速度

没有 usage 的请求仍可有时间线,但不进入 token 分布;缓存分布还要求引擎报告缓存命中数。

vLLM / SGLang 流式请求由网关请求 usage,并去掉为统计额外取得的 usage 块,保持客户端原有回复。 TensorFold、Strata 内置模板的回复带 usage,其他 callable 引擎需自行提供。

没有排队或 Prefill 拆分

vLLM 需要返回逐请求耗时(--enable-per-request-metrics);0.25.0 及以上镜像的新部署默认开启,旧版本或未知版本默认不传,可手动选择但须确认镜像支持。 TensorFold、Strata 内置模板报告 Prefill 与 Decode,不报排队;SGLang 暂不拆。

请求记录缺失

记录保留 7 天,存储超过 2 GB 时会提前删除最老的一天。

每秒超过 300 条时正常请求按比例保存,异常请求(非 2xx、断开、截断、首个输出 ≥ 10 秒)保留。 一行可能代表多个请求,悬停查看权重;分布和计数不受列表抽样影响。

写入跟不上时也可能丢记录。未保存的请求不能从列表或 ID 搜索找回。

API 方式可使用 GET /api/v1/monitor/deployments/{id}/requests、GET /api/v1/monitor/requests/lookup、 GET /api/v1/monitor/distributions,参数见 API 参考。

3. 看实例事件和实时日志

在部署页打开实例详情,事件时间线(状态变化、调度结果、错误)和日志合并在同一条时间线里。实例运行中显示实时日志;容器退出后显示已持久化的日志,也可以选择一个历史时间范围回看。启动失败时实例和日志会保留,先在这里看错误再改参数重试。

4. 在「日志」页检索

从实例详情确定时间段和实例 ID 后,打开侧边栏日志检索历史记录;节点、agent 和 server 日志也可以在这里查询。

  1. 选过滤条件,可以任意组合:

    条件说明
    实例前缀匹配,填 8 位短 ID 即可
    级别level=warn 表示 ≥warn,即 warn 及更高
    来源source=instance|node|agent|server;不指定时 API 默认 instance
    时间范围页面提供最近 30 分钟到 7 天、全部等预设;选自定义可精确到秒指定起止时间
    关键字全文检索,例如 CUDA out of memory
  2. 看结果。关键字留空时回退为最近日志(相当于 tail)。结果多于一页时点加载更多;命中数封顶 100 万,超过统计上限时显示为 N+,不是精确总数。

  3. 展开上下文。对单条命中点上下文,可看它前后若干行(每侧最多 1000 行)。查 agent、server 日志时用节点和来源限定范围,不要沿用实例过滤条件。

  4. 看直方图。搜索结果上方按时间桶 × 级别统计日志量(红为 error/fatal,蓝为其余级别,含没有级别的行),使用当前过滤条件;点击某根柱子即把时间范围缩小到该时间桶(切为“自定义”),新范围按更细的时间桶重画,可继续点击逐级下钻。

  5. 回到原始事件。命中里的级别、时间、来源和实例 UUID 可以对回实例详情里的对应事件。

通过 API 检索时,使用 GET /api/v1/logs/search,加 with_total=1 取命中数,用 cursor_ts / cursor_id 翻页。 上下文用 GET /api/v1/logs/context?instance=..&ts=..&id=..&before=..&after=..;agent、server 等没有实例 UUID 的日志改用 node 限定范围。 直方图用 GET /api/v1/logs/histogram,过滤条件与检索一致;完整参数见 API 参考。

节点与 server 断开期间(server 重启或升级、网络中断),agent 把实例、节点和 agent 自身的日志暂存在内存里,重连后按原顺序补发,期间的日志照常能检索到。暂存上限 16 MiB,断开太久写满时丢弃最早的日志,并在丢弃处补一条 warn 级说明(英文原文以 gpuworks: N log lines from … to … were dropped 开头,可按 were dropped 检索);agent 进程重启会丢失还没发出的部分。断开期间的指标不补发。

server 与 agent 自身的日志

  • 哪些进日志页:server 与 agent 只把 warn 及以上的记录送进日志中心;info 及以下只写各自的日志文件(server 的 logs/gpuworks-server.log、agent 的 <state>/agent.log)。
  • 重复日志会被压缩:同一类记录在 30 秒内最多写 10 条(debug 记录只压完全相同的行,30 秒最多 50 条),其余只计数;窗口结束后补一条 suppressed similar log messages,带被压的原消息(message)、条数(suppressed)与时间窗(since、window)。 「同一类」指级别、消息与记录者自带的字段都相同,server 另按错误码、原因、请求方法、路径与状态码区分,agent 另按错误码与原因区分;同时活跃的类别超过 4096 个时,新类别只按消息计数。 因此一个客户端反复以错误凭据访问同一路径、或一个厂商工具每次探测都失败,只留下几行和一个计数。
  • 请求被拒的原因在访问日志里:server 每个请求一行 http request;返回产品错误时这一行带 code(错误码)和 error_params(错误参数的 JSON,例如调度拒绝的节点、原因与显存数字),弹窗关掉后仍可查。
  • 镜像检查:agent 每分钟检查一遍目录镜像,只在结论变化时写 info:image present(带运行时返回的 image_id)或 image no longer present; 镜像不存在是正常结论,不写告警;检查命令本身失败时写 warn image presence inspection failed。
  • 调度拒绝:deployment not schedulable yet 与调度事件同时写,同一原因在一个等待窗口(默认 10 分钟)内只写一次。

临时采集调试日志与请求原文

  1. 管理员打开设置 → 诊断 → 调试采集(/settings#diagnostics),选择要排查的部署并开始采集。部署所在节点会自动加入;只选节点不会记录部署请求原文。默认采集 10 分钟、上限 10 GiB,可手动停止,无需重启引擎。
  2. 在采集期间复现问题,并记录客户端收到的 X-Request-ID、时间与状态码。确认相关节点状态为采集中;离线、旧版不支持或采集失败的节点不能当作已采集。
  3. 停止后,在同一页创建收集诊断信息,时间范围覆盖复现过程,包含相应部署、节点和调试采集,再下载诊断包。调试会话中可找到 server.log、节点调试日志,以及 requests/<部署 ID>-<请求 ID>.jsonl。

调试文件在会话有效且未达到大小上限时保留重复的原始记录,包括 debug;普通日志文件与日志中心仍按上述规则限频,不能用普通日志的明细行数当作失败请求总数。停止、到期或达到上限后,恢复配置的普通日志级别。原文含请求与响应内容,分享前需检查敏感数据。

请求 JSONL 的 end 记录表示网关观察到的结果:响应头之前的上游 EOF 会保留 read_error(例如 EOF),并标记 outcome=upstream_error;正常响应结束不应把 body EOF 记成错误。流式回复实际返回且未超出采集上限时,可在 upstream / client 数据中检查 finish_reason 与 data: [DONE]。网关准备的请求快照不证明引擎已收到;缺少 [DONE] 也不能单凭这一点确定断开位置。

设置引擎日志级别

SGLang 默认日志不带级别,平台的级别过滤和直方图就看不到真正的错误。SGLang 单卡、引擎接管模式下,平台会在适用时自动注入带级别的日志配置,日志仍写入容器 stderr。

日志级别在快捷部署的功能区直接选择:

  • 默认 INFO;可换成其他级别,或选未设置。选项和默认值由服务端参数字典提供,表单提交所选值。
  • 切换快捷/专家模式不会丢失这个选择。
  • 未设置表示不带 --log-level,也就不注入配置,由引擎决定默认级别。

部署命令预览里能看到 SGLANG_LOGGING_CONFIG_PATH 和写入配置的启动前脚本,实例详情也可以查看保存的脚本和 env。/tmp/gpuworks-sglang-logging.json 是配置文件,不是日志输出文件。

哪些启动方式不会自动注入、多卡并行时日志为什么仍可能没有级别、怎么自己接管完整脚本,见SGLang 日志注入的行为与边界。

这篇文档有帮助吗?