Java 虚拟线程怎样识别 pinned 场景

定位虚拟线程 pinned，先问运行版本，再问录到了什么。看到 WAITING、同步代码或接口变慢，都不足以单独证明载体线程被钉住。本文只处理原因识别和观测边界，不把一次录制包装成吞吐量结论。

Java 官方虚拟线程说明：https://docs.oracle.com/en/java/javase/25/core/virtual-threads.html。命令须使用与目标进程匹配的 JDK 工具，并具备 attach 权限；容器中还要确认 PID 命名空间及写入路径。

先按运行中的 JDK 划定判断范围

pinned 指虚拟线程在阻塞时不能从 carrier 卸载；影响主要是载体资源利用，而不是天然意味着计算结果错误。排查表首先写入实际 JVM 版本，不要用终端默认 java 的版本替代服务进程版本。

# 改为目标服务进程号，后续命令均使用同一进程
PID=12345
# 查询目标 JVM，而非仅查询当前 shell 的默认 Java
jcmd "$PID" VM.version

JDK 21–23 的同步块内阻塞，是旧版本排查的重要入口。JDK 24 引入 JEP 491，改变了同步监视器相关的钉住行为；不能在新版本中沿用“有 synchronized 就会 pinned”的判断。native 方法或 foreign function 仍是需要结合实际调用栈关注的边界。这里的版本分界不等于任何第三方 JDK 都无需核对补丁和发行说明。

版本变化改变的是归因规则：同一段同步代码在不同运行时中，不能仅凭源码相同就预设事件相同。本文不使用旧诊断开关作为跨版本通用证据，也不建议先全局替换锁再寻找原因。

用短时 JFR 录制捕获事件

选择能覆盖问题发生的短窗口，把开始时间、流量场景、文件路径和 JVM 版本一起记下。下面是待执行的示例命令，不是本站服务的实测日志。文件路径必须在目标 JVM 所处环境中可写；录制文件可能包含敏感调用信息，应按诊断材料管理。

# 先建立权限适当的诊断目录，再把下列路径改成目标 JVM 可写的位置
# profile 比 default 收集更多数据，执行前评估生产诊断开销
jcmd "$PID" JFR.start name=pinning settings=profile duration=60s filename=/var/tmp/pinning.jfr
# 等待这次录制自然结束后，在具有文件读取权限的环境中查看事件
jfr print --events jdk.VirtualThreadPinned /var/tmp/pinning.jfr

jdk.VirtualThreadPinned 默认启用，官方说明的默认阈值为 20 ms，但自定义配置可以改变记录条件。先确认实际录制配置，再解释事件数量。事件存在时，记录持续时间、事件线程、时间戳和可用栈帧；不要只留下一个总数。

没有输出，只能说明这份文件没有显示该类事件。问题不在录制窗口内、事件配置不符或持续时间未越过阈值，都可能使这次观察不足。也不要假设所有 native 阻塞都会以相同形式出现在该事件里。

把事件栈和线程转储放回同一时间窗口

线程转储用于了解采样时刻任务停在哪里，而 JFR 事件用于保留录制期间符合条件的事件。二者不能互相替代：一个瞬时快照没有事件的持续时间信息，一次已结束的事件也不保证随后转储仍保留相同栈。

# 在问题窗口内另取快照，路径同样由目标 JVM 写入
jcmd "$PID" Thread.dump_to_file -format=text /var/tmp/virtual-threads.txt

使用支持虚拟线程的转储形式，而不是假定任意传统转储都能完整描述它们。该格式与传统转储的信息范围不同，不应期待从中得到完整锁对象细节。对照时保留线程标识与名称、时间、业务入口和库版本；线程名称可能重复，不能只按名字把两份材料强行合并。

区分 pinned、锁竞争和普通等待

普通等待描述任务暂时没有继续执行；锁竞争描述多个任务争用受保护资源；pinned 关注不能卸载与载体占用。它们可以在同一个业务路径出现，却不是同义词。长耗时还可能来自下游服务、连接池容量或 CPU 计算，不能把所有延迟都归到虚拟线程调度。

分析事件栈时，从业务调用点向底层库展开：先标注阻塞位置，再根据运行版本检查同步或 native/foreign 边界。栈里出现 synchronized 只是待解释的上下文，不是独立结论。需要库源码或平台原生诊断才能确认的部分，应写成待确认，而不是猜出一个 JNI 根因。

对于 JDK 24 及之后的运行时，仍然值得缩小锁的范围以降低竞争，但那是并发设计问题，不能当成 pinned 已被证实。对于旧版本，同步范围与阻塞路径交叠值得重点追踪，也仍需事件和具体栈支持。

形成有边界的定位记录

一条可交接的记录应包含：运行版本与发行版、录制开始及结束时间、实际事件设置、事件持续时间与栈、同窗口转储位置，以及尚未确认的调用边界。若暂时只有等待栈，结论写“发现等待位置，尚无 pinned 事件证据”；若已有事件，写清它对应哪段调用，而不是宣布整个服务都被钉住。

最终判断分三层：观察事实、可能原因、需要补充的材料。把这三层分开，后续人员才能继续定位，也能避免在运行时已经改变同步语义后，仍套用旧版本的排障清单。

参考：Oracle JDK 25 虚拟线程说明；JEP 444 的初始设计背景；Java 团队的 JEP 491 版本说明；jcmd 命令参数。