How do you detect virtual-thread pinning in a running Java application?
answer
- tracePinnedThreads: JDK 21-23 only, gone in 24
- JFR jdk.VirtualThreadPinned event + threshold
- Analyze with JMC or jfr print
- Companion: jdk.VirtualThreadSubmitFailed
- Symptom: throughput plateaus, carrier pool saturated
basics
~20 sRecord with JDK Flight Recorder and look for jdk.VirtualThreadPinned events, which show where a pinned virtual thread blocked. On JDK 21 to 23, -Djdk.tracePinnedThreads also printed a stack trace, but JDK 24 removed that property.
solid answer
~50 sTwo tools, depending on the JDK. On JDK 21–23, starting the JVM with `-Djdk.tracePinnedThreads=full` (or `short`) logs a stack trace each time a virtual thread *blocks while pinned*, pointing at the offending `synchronized` or native frame; JDK 24 removed the property, and setting it now has no effect. On every version, the tool is **JDK Flight Recorder (JFR)**: the `jdk.VirtualThreadPinned` event is enabled in JFR's default settings with a 20 ms threshold, so a recording captures meaningful pins with their stack traces, and since JDK 24 it also names the reason for the pin and the carrier. Analyze the `.jfr` file in JDK Mission Control or with `jfr print --events jdk.VirtualThreadPinned`. JFR is low-overhead enough to leave on in production. You can also infer pinning indirectly from symptoms: rising latency under load with a fully-utilized but small carrier pool.
go deeper
Knows that JFR's jdk.VirtualThreadPinned event shows where pinning happens, and that -Djdk.tracePinnedThreads did the same only on JDK 21 to 23.
Can record and read a jdk.VirtualThreadPinned stack trace (or, on JDK 21 to 23, tracePinnedThreads output) to find the synchronized or native frame at fault.
Leads with JFR (jdk.VirtualThreadPinned with its threshold, pin reason and carrier, analyzed in JMC or jfr print), knows tracePinnedThreads was removed in JDK 24, and correlates symptoms (plateaued throughput, saturated carriers).
Designs continuous observability: JFR always-on with pinned-event alerting, dashboards on carrier saturation and submit-failed events, and a playbook tying detection to the remediation for each service's JDK (ReentrantLock on 21 to 23, isolating native calls on any version).
## Why detection needs tooling Pinning is invisible in normal logs: code runs correctly, just *less concurrently* than you expect. A pinned virtual thread holds its carrier OS thread, so the symptom is throughput that plateaus far below what the number of virtual threads should allow. To find *where* it happens you need the runtime to tell you, which is what these tools do. ## Tool 1: `-Djdk.tracePinnedThreads` (JDK 21 to 23 only) Added with virtual threads, this **system property** makes the JVM print a stack trace **whenever a virtual thread blocks while pinned**. Two modes: - `=short` — a one-line-per-frame summary highlighting the frame that caused the pin. - `=full` — the complete stack trace, with the pinning frame marked (e.g., a `synchronized` monitor or a native method). It is a **diagnostic** tool: under load it can be very noisy, and JEP 491 notes it proved problematic because the stack traces are printed while executing critical code, so you run it in testing or staging, not steady-state production. **Important:** JEP 491 **removed** it in JDK 24; on JDK 24, 25 or 27 setting it has no effect and prints nothing. So mention it for JDK 21 to 23, but lead with JFR. ## Tool 2: JDK Flight Recorder (JFR) — the modern answer **JFR** is a built-in, very-low-overhead event-recording framework in the JVM. It emits structured events you capture into a `.jfr` file. The relevant event is: - **`jdk.VirtualThreadPinned`** — emitted when a virtual thread blocks while pinned, including the stack trace and the duration it was pinned. JFR's default settings enable it with a **20 ms threshold**, so harmless micro-pins are ignored and the real ones surface. Since JDK 24 it also records the **reason** for the pin (for example `VM call to Foo.<clinit> on stack` for blocking inside a static initializer) and the **carrier thread**. - **`jdk.VirtualThreadSubmitFailed`** — emitted when starting or unparking a virtual thread fails, probably because of a resource issue; a companion signal, not a pinning detector. How to use it: 1. Start a recording: `-XX:StartFlightRecording=duration=60s,filename=rec.jfr`, or attach at runtime with `jcmd <pid> JFR.start`. 2. The default settings already enable the pinned event; to see shorter pins, lower its threshold in a custom `.jfc` settings file. 3. Analyze: open `rec.jfr` in **JDK Mission Control (JMC)** for a GUI, or run `jfr print --events jdk.VirtualThreadPinned rec.jfr` on the command line to dump events and their stack traces. Because JFR overhead is tiny, you can run it continuously in production and alert on pinned-thread events—this is the recommended observability strategy. ## Tool 3: indirect / symptom-based detection Even without flags you can suspect pinning from behavior: latency climbs under concurrency, the carrier pool (default size = CPU count, configurable via `jdk.virtualThreadScheduler.parallelism`) is saturated, and adding more virtual threads doesn't help. A thread dump corroborates it: a pinned virtual thread is mounted, so `jstack` or `jcmd <pid> Thread.print` shows it under its carrier (`Carrying virtual thread #N`, then `Mounted virtual thread #N` and its stack), and `jcmd <pid> Thread.dump_to_file` lists every virtual thread. Look for ones stuck in native frames, or inside `synchronized` on JDK 21 to 23. APM/continuous-profiling products increasingly surface the JFR pinned event directly. ## Summary of what a strong answer states - `jdk.tracePinnedThreads=full|short` for ad-hoc diagnosis on JDK 21 to 23 only (removed in JDK 24). - JFR `jdk.VirtualThreadPinned` (with threshold) + JMC/`jfr print` as the production-grade, low-overhead method, plus `jdk.VirtualThreadSubmitFailed` as a companion. - Symptom-level signs: plateaued throughput, saturated small carrier pool, thread dumps showing virtual threads stuck in native frames (or in synchronized on JDK 21 to 23).
- Why prefer JFR over jdk.tracePinnedThreads in production?JFR is low-overhead, enables this event by default with a 20 ms threshold so you only record meaningful pins, produces structured analyzable events, and integrates with JMC and continuous profiling. tracePinnedThreads was noisy, printed while executing critical code, and was removed in JDK 24, so on 25 or 27 it does nothing.
- You see throughput plateau but no obvious deadlock. How do you confirm it's pinning?Take a JFR recording with jdk.VirtualThreadPinned enabled (low threshold) and inspect the stack traces and pin reasons, or take a jcmd <pid> Thread.dump_to_file dump and look for virtual threads stuck in native frames (or inside synchronized on JDK 21 to 23) while the small carrier pool is saturated.
- Recommending -Djdk.tracePinnedThreads on JDK 24 or later—it was removed and setting it does nothing
- Saying you must use a third-party agent; JFR is built into the JDK
- Claiming JFR has high overhead—it is designed as a low-overhead recorder for production
- Confusing detecting pinning with detecting deadlocks (jstack); pinning needs the pinned-thread event
- JFR jdk.VirtualThreadPinned event
- Java 21pre-release 19
- jdk.tracePinnedThreads system property
- Java 21pre-release 19removed 24
Assumes JDK 27. Virtual threads were a preview in JDK 19 and 20 and are final since JDK 21. Synchronized stopped pinning virtual threads in JDK 24 (JEP 491), which also removed jdk.tracePinnedThreads, so JDK 25 LTS behaves like 27 for synchronized; on JDK 21 to 23 synchronized pins and the property works. The jdk.VirtualThreadPinned event and the jdk.tracePinnedThreads property both first shipped with the JDK 19 virtual-thread preview.
context
- JEP 491: Synchronize Virtual Threads without Pinningopenjdk.org
- JEP 444: Virtual Threadsopenjdk.org