Virtual Thread Time measures virtual thread mounted time and scheduling activity on the JVM.
Check support and initialize the library once during application startup:
if (VirtualThreadTime.isSupported()) {
VirtualThreadTime.initialize();
}Report whether the hooks are measuring, since trackers read as zero in an AOT cache training run and freeze if another agent removes the hooks:
if (VirtualThreadTime.isSupported()) {
log.info("Virtual thread time status: %s", VirtualThreadTime.status());
}Register and use a tracker from the virtual thread being measured:
try (VirtualThreadTime time = VirtualThreadTime.register()) {
long mountedStart = time.mountedTimeNanos();
long mountsStart = time.mountCount();
// Run virtual-thread work.
long mountedNanos = time.mountedTimeNanos() - mountedStart;
long mounts = time.mountCount() - mountsStart;
}Mounted time is the CPU time of the carrier thread while the virtual thread is mounted on it. Time spent unmounted while sleeping, parking, or waiting for I/O is excluded. So is time the carrier spends off the CPU while the virtual thread is mounted: waiting in the OS run queue when the scheduler has more carriers than cores, or blocked while the virtual thread is pinned. Kernel time spent on behalf of the virtual thread is included, and so is steal time a hypervisor reports, on Linux carriers that read the perf task-clock event described below. A tracker is confined to the virtual thread that registered it.
At initialization the library creates a JVMTI environment and uses it once to
retransform java.lang.VirtualThread, injecting a call into its mount() and
unmount() methods. The call is guarded by an inline null
check of the thread's thread-local map, so a virtual thread that has never used
a thread local pays only that check, and a registered thread finds its tracker
through a thread local and stamps it with the carrier's CPU clock. The hook
class is defined into the bootstrap class loader, which is the only loader
VirtualThread can call into. No per-thread JVMTI state is created.
The only JVMTI event left enabled is the class file load hook, which costs a
name comparison per class loaded afterwards, and 3.7–6.2 µs for each class
loaded from a CDS archive after initialize() (AppCDS, or an AOT cache with
class linking off), because HotSpot re-reads the archived bytes to post the
event: roughly 110–185 ms for 30,000 classes. With the AOT cache's default
class linking it costs nothing, since those classes are loaded before main.
The event stays on because HotSpot rebuilds a retransformed class from its
original bytes and consults only the environments with that event enabled: the
library serves the hooked bytes again whenever another agent later retransforms
VirtualThread from the same input, and the hooks survive. If the input
differs, because another agent redefined the class or an agent registered
before the library now changes it, the hooks cannot be reapplied; the library
then reports Status.HOOKS_REMOVED, and trackers keep the totals of the
intervals that were closed by then and count nothing new.
The retransformation depends on the structure of VirtualThread in JDK 25.
When it cannot be applied, initialize() throws UnsupportedOperationException
whose cause names the step that failed, and isSupported() returns false;
the failure holds for the process.
A JVM recording an AOT cache (-XX:AOTCacheOutput or -XX:AOTMode=record)
does not get the hooks: retransforming VirtualThread would exclude it from
the cache as redefined, HotSpot refuses to write a cache without that critical
class, and the training run would exit with a failure while a production run
with -XX:AOTMode=auto would silently start without any class sharing. In such
a run initialize() succeeds, status() reports AOT_TRAINING and trackers
count nothing. A cache trained this way works with the hooks at run time.
Creating any JVMTI environment, this library's included, makes HotSpot take a
slower path at every virtual-thread transition for the rest of the process.
APM agents, profilers and debuggers pay the same path, so a JVM that already
runs one adds nothing here. The experimental flag
-XX:+UnlockExperimentalVMOptions -XX:-DoJVMTIVirtualThreadTransitions
removes it, at the price of JVMTI no longer reporting virtual threads to any
agent or debugger in that JVM; the hooks do not need those events and then
measure at close to the cost of a bare transition.
On Linux, reading a thread's CPU clock is a system call, not a vDSO read. Each carrier therefore opens a perf task-clock event for itself the first time it reads its clock, maps the event's page, and from then on reads the clock from that page without a system call. The event counts the time the carrier is scheduled on a CPU, including kernel time and, where the hypervisor reports it, steal time, which the system call leaves out. Each such carrier holds one perf file descriptor and one page charged to the user's perf locked-memory limit until its thread exits.
A carrier can use the perf task-clock event only when:
- it may open the event:
perf_event_paranoidat 2 or lower, as on Amazon Linux 2023,CAP_PERFMONon Ubuntu 24.04, orCAP_SYS_ADMINon the tested Debian 12 kernel; - the kernel publishes timing data for user-space extrapolation
(
cap_user_time). Graviton does; x86 KVM guests using kvm-clock, the EC2 Intel default, do not; Intel with a native scheduler clock, on bare metal or booted withno-kvmclock, can; - no seccomp filter applies to it, by default. Some filters kill the process
instead of failing the call, such as systemd's
SystemCallFilter=withoutSystemCallErrorNumber=, so a carrier tries the event only when its/proc/thread-self/statusreports no seccomp filter. Withio.airlift.vthreadtime.perf.clock=on, a filter that allowsperf_event_openalso works, such as Docker's default profile with--cap-add PERFMON.
After the first carrier fails to set up the event, no later carrier tries.
Carriers without an event read the thread CPU clock with a system call. The
property io.airlift.vthreadtime.perf.clock, described under
Dependency, selects whether carriers try the event.
The two clocks do not agree exactly. Measured on AWS Graviton4, the perf
task-clock event differed from the thread CPU clock by about 0.2–0.3 µs per
time-slice switch, and read up to about 0.85 µs per switch lower under
frequent wakeup preemption: 0.8% of the CPU time of a thread sharing its CPU
with a task that woke every 50 µs. If native code on a carrier disables its
perf events with prctl(PR_TASK_PERF_EVENTS_DISABLE), later readings on that
carrier also count time off the CPU, which the library cannot detect.
After the first successful initialization:
-
All virtual threads: Every mount and unmount runs HotSpot's JVMTI transition path and the injected null check. Measured on EC2 in November 2026 with a zero-work
Thread.yield()loop, a JVMTI agent attached (a server that monitors thread usage already runs one) and an OpenTelemetry context current so the measured thread has thread locals and the null check does not skip the call, the hooks add per mount/unmount cycle:JDK 25 / 27 Graviton5 (c9g) Graviton4 (c8g) Intel (c7i) Intel Xeon 6 (c8i) Hooks +7 / +7 ns +9 / +6 ns +14 / +7 ns +9 / +10 ns JVMTI mount and unmount events (release 1.1) +69 / +92 ns +92 / +119 ns +121 / +117 ns +132 / +126 ns HotSpot's JVMTI slow path itself costs 46–90 ns per cycle on these hosts, which any agent pays. There is no useful universal percentage: the cost is fixed per transition, so its relative weight shrinks as useful work between transitions grows, and it is most visible in transition-only loops. Merely adding the library to the class path or module path has no effect.
-
Memory: No native memory per virtual thread. A virtual thread that uses thread locals but is not registered gets one empty thread-local entry of about 40 bytes on its first mount. On Linux, each carrier that reads the perf task-clock event also holds a small allocation, a file descriptor and a locked page until its thread exits.
-
Registered threads: The hooks read the carrier thread's CPU clock at each mount and unmount, and
mountedTimeNanos()reads it once more. On hosts where carriers read the perf task-clock event, such as AWS Graviton, this costs a fraction of the system call. On Graviton5 in November 2026, against the same build with the event turned off:Graviton5 (c9g) Perf task-clock event System call Tracking, per mount/unmount cycle 56 ns 327 ns mountedTimeNanos()call31 ns 167 ns Tracking, per park in the blocked-handoff benchmark not measurable 0.1 µs Where carriers read the thread CPU clock with a system call, as on AWS Intel with kvm-clock, tracking costs about 340–400 ns per cycle and a
mountedTimeNanos()call about 150 ns. On EC2, registering and closing a short-lived virtual thread costs 0.5–0.9 µs of CPU, against about 3 µs with the events of release 1.1. -
Pathological transition rates: The problematic cases remain loops that repeatedly call
Thread.yield()orparkNanos()with almost no useful work between transitions, where the fixed cost per transition dominates. The library exposesmountCount()andunmountCount()so integrations can detect this pattern.
All of these measurements are described in Measuring runtime overhead, including the November 2026 perf task-clock measurements on AWS Graviton5, Graviton4 and Intel and the release 1.1 numbers for the JVMTI events the hooks replaced.
Virtual Thread Time requires a HotSpot-based JVM, Java 25 or newer; the build
verifies 25, 26, 27 and 28-ea. The hooks depend on the structure of
java.lang.VirtualThread; on a JVM where the retransformation does not apply,
initialize() throws and isSupported() returns false. A runtime image
built with jlink must include the jdk.management module, which the library
reads the AOT options through.
Applications using the class path must enable native access for unnamed modules:
--enable-native-access=ALL-UNNAMED
Applications using the module path can grant native access specifically to Virtual Thread Time:
--enable-native-access=io.airlift.vthreadtime
Linux and macOS 15 or newer are supported on aarch64 and x86_64. Linux
artifacts require glibc 2.17 or later and dynamically link the host's
standard C runtime libraries; musl-based distributions such as Alpine Linux
are not supported. Other operating systems and architectures are unsupported.
On those platforms, or when the native library cannot be loaded,
VirtualThreadTime.isSupported() returns false.
The Java API has no additional Maven runtime dependencies. The native host runtime requirements above still apply.
Virtual Thread Time is published as io.airlift:vthreadtime.
<dependency>
<groupId>io.airlift</groupId>
<artifactId>vthreadtime</artifactId>
<version>${vthreadtime.version}</version>
</dependency>Release artifacts contain the native libraries for all supported platforms.
The appropriate library is extracted and loaded when Virtual Thread Time is
initialized. All class loaders in a JVM use the same extracted library, which
remains loaded until the JVM exits. Native initialization is also process-wide:
its first success or failure is retained until JVM exit, and later class
loaders do not retry. No -agentpath JVM option is required.
The system property io.airlift.vthreadtime.library.path can specify an
explicit native library instead of loading the packaged resource. The system
property io.airlift.vthreadtime.tmpdir can select the extraction directory
when the default java.io.tmpdir does not permit executable mappings. The
system property io.airlift.vthreadtime.perf.clock controls the perf
task-clock event on Linux: auto, the default, tries it only on carriers with
no seccomp filter; on also tries it under a seccomp filter, such as Docker's
default profile with --cap-add PERFMON, and must not be used where a filter
kills the process on perf_event_open; off never opens a perf event. With
on, a failure to open the event still falls back to the system call. Any other
value makes initialization fail on every platform, so
VirtualThreadTime.isSupported() returns false. These properties must be
configured before the first use of Virtual Thread Time and must not be changed
afterward; this includes java.io.tmpdir when no custom extraction directory
is configured.
All class loaders rendezvous through a predictable process-specific directory
inside the configured extraction root. The loader rejects a precreated
rendezvous directory owned by another user, so simple predictable-name
squatting fails closed instead of loading attacker-supplied code. On a shared
host, however, another local user who can create entries in the extraction root
can cause initialization to fail for the lifetime of the JVM. Applications that
do not trust other local users must configure io.airlift.vthreadtime.tmpdir to
a directory owned by the application user with 0700 permissions.
A C23 compiler, a Java 25 JDK, and on Linux, kernel headers 5.9 or later are required:
./mvnw clean installA library built this way requires the build host's glibc or newer. Release
builds compile the Linux libraries with the gcc of PyPA's manylinux2014 image,
which links against glibc 2.17, using the perf_event.h of Linux 6.12 because
the image's kernel headers are older. CI checks that each library loads on
CentOS 7; see .github/workflows/native-build.yml.