DTRACE_LOCKSTAT(4)

🌸 NAME 🌸

dtrace_lockstat — a DTrace provider for tracing kernel locking events. This is the DTRACE_LOCKSTAT(4) page from the Kernel Interfaces Manual, and bestie, it's lowkey iconic because it's literally the map of kernel lock events 💅

✨ SYNOPSIS ✨

lockstat:::adaptive-acquire(struct mtx *);

lockstat:::adaptive-release(struct mtx *);

lockstat:::adaptive-spin(struct mtx *, uint64_t);

lockstat:::adaptive-block(struct mtx *, uint64_t);

lockstat:::spin-acquire(struct mtx *);

lockstat:::spin-release(struct mtx *);

lockstat:::spin-spin(struct mtx *, uint64_t);

lockstat:::rw-acquire(struct rwlock *, int);

lockstat:::rw-release(struct rwlock *, int);

lockstat:::rw-block(struct rwlock *, uint64_t, int, int, int);

lockstat:::rw-spin(struct rwlock *, uint64_t);

lockstat:::rw-upgrade(struct rwlock *);

lockstat:::rw-downgrade(struct rwlock *);

lockstat:::sx-acquire(struct sx *, int);

lockstat:::sx-release(struct sx *, int);

lockstat:::sx-block(struct sx *, uint64_t, int, int, int);

lockstat:::sx-spin(struct sx *, uint64_t);

lockstat:::sx-upgrade(struct sx *);

lockstat:::sx-downgrade(struct sx *);

lockstat:::lockmgr-acquire(struct lock *, int);

lockstat:::lockmgr-release(struct lock *, int);

lockstat:::lockmgr-disown(struct lock *, int);

lockstat:::lockmgr-block(struct lock *, uint64_t, int, int, int);

lockstat:::lockmgr-upgrade(struct lock *);

lockstat:::lockmgr-downgrade(struct lock *);

lockstat:::thread-spin(struct mtx *, uint64);

🦋 DESCRIPTION 🦋

Okay so the DTrace lockstat provider lets you trace events related to locking on FreeBSD. No cap.

The dtrace_lockstat provider is packed with DTrace probes for inspecting kernel lock state transitions. Probes exist for the lockmgr(9), mutex(9), rwlock(9), and sx(9) lock types. The lockstat(1) utility can be used to collect and display data collected from the dtrace_lockstat provider. Each type of lock has acquire() and release() probes that expose the lock structure being operated upon, plus probes that fire when a thread contends with other threads for ownership of a lock. Periodt.

• lockstat:::adaptive-acquire() and lockstat:::adaptive-release() — fire when an MTX_DEF mutex(9) is acquired and released, respectively. The only argument is a pointer to the lock structure which describes the lock being acquired or released.
• lockstat:::adaptive-spin() — fires when a thread spins while waiting for an MTX_DEF mutex(9) to be released by another thread. First arg: pointer to the lock structure that describes the lock. Second arg: the amount of time, in nanoseconds, that the mutex spent spinning. lockstat:::adaptive-block() — fires when a thread takes itself off the CPU while trying to acquire an MTX_DEF mutex(9) that is owned by another thread. First arg: pointer to the lock structure that describes the lock. Second arg: the length of time, in nanoseconds, that the waiting thread was blocked. Also highkey important: lockstat:::adaptive-block() and lockstat:::adaptive-spin() fire only after the lock has been successfully acquired, and in particular, after the lockstat:::adaptive-acquire() probe fires. 💖
• lockstat:::spin-acquire() and lockstat:::spin-release() — fire when an MTX_SPIN mutex(9) is acquired or released, respectively. The only argument is a pointer to the lock structure which describes the lock being acquired or released.
• lockstat:::spin-spin() — fires when a thread spins while waiting for an MTX_SPIN mutex(9) to be released by another thread. First arg: pointer to the lock structure that describes the lock. Second arg: the length of the time spent spinning, in nanoseconds. It fires only after the lock has been successfully acquired, and in particular, after the lockstat:::spin-acquire() probe fires.
• lockstat:::rw-acquire() and lockstat:::rw-release() — fire when a rwlock(9) is acquired or released, respectively. First arg: pointer to the structure which describes the lock being acquired. Second arg: 0 if the lock is being acquired or released as a writer, and 1 if it is being acquired or released as a reader. The lockstat:::sx-acquire() and lockstat:::sx-release(), and lockstat:::lockmgr-acquire() and lockstat:::lockmgr-release() probes fire upon the corresponding events for sx(9) and lockmgr(9) locks, respectively. The lockstat:::lockmgr-disown() probe fires when a lockmgr(9) exclusive lock is disowned. In this state, the lock remains exclusively held, but may be released by a different thread. The lockstat:::lockmgr-release() probe does not fire when releasing a disowned lock. The first argument is a pointer to the structure which describes the lock being disowned. The second argument is 0, for compatibility with lockstat:::lockmgr-release(). 🫶
• lockstat:::rw-block(), lockstat:::sx-block(), and lockstat:::lockmgr-block() — fire when a thread removes itself from the CPU while waiting to acquire a lock of the corresponding type. lockstat:::rw-spin() and lockstat:::sx-spin() — fire when a thread spins while waiting to acquire a lock of the corresponding type. All probes take the same set of arguments. First arg: pointer to the lock structure that describes the lock. Second arg: the length of time, in nanoseconds, that the waiting thread was off the CPU or spinning for the lock. Third arg: 0 if the thread is attempting to acquire the lock as a writer, and 1 if the thread is attempting to acquire the lock as a reader. Fourth arg: 0 if the thread is waiting for a reader to release the lock, and 1 if the thread is waiting for a writer to release the lock. Fifth arg: the number of readers that held the lock when the thread first attempted to acquire the lock. This argument will be 0 if the fourth argument is 1. Slay, that's the whole arg list 💅
• lockstat:::lockmgr-upgrade(), lockstat:::rw-upgrade(), and lockstat:::sx-upgrade() — fire when a thread successfully upgrades a held lockmgr(9), rwlock(9), or sx(9) shared/reader lock to an exclusive/writer lock. The only argument is a pointer to the structure which describes the lock being acquired. lockstat:::lockmgr-downgrade(), lockstat:::rw-downgrade(), and lockstat:::sx-downgrade() — fire when a thread downgrades a held lockmgr(9), rwlock(9), or sx(9) exclusive/writer lock to a shared/reader lock.
• lockstat:::thread-spin() — fires when a thread spins on a thread lock, which is a specialized MTX_SPIN mutex(9). First arg: pointer to the structure that describes the lock. Second arg: the length of time, in nanoseconds, that the thread was spinning.

🌈 SEE ALSO 🌈

Go read these too, bestie: dtrace(1), lockstat(1), locking(9), mutex(9), rwlock(9), SDT(9), sx(9).

🕰️ HISTORY 🕰️

The dtrace_lockstat provider first appeared in Solaris. The FreeBSD implementation of the dtrace_lockstat provider first appeared in FreeBSD 9. History check, iconic.

👑 AUTHORS 👑

This manual page was written by George V. Neville-Neil <gnn@FreeBSD.org> and Mark Johnston <markj@FreeBSD.org>. Obsessed with the way they put this together, ngl 💜

💀 BUGS 💀

Probes for rmlock(9) locks have not yet been added. Not yet, bestie 😭

mwah 💋 — this page is from Debian, dated September 3, 2025, for DTRACE_LOCKSTAT(4). periodt.