lockstat(1M)
NAME
lockstat − report kernel lock statistics
SYNOPSIS
lockstat [ −ACEH ] [ −e event list ] [ −b | −t | −h | −s depth ]
[ −n nlocks ] [ −l lock[,size] ] [ −d duration ] [ −T ]
[ −cwWRp ] [ −D count ] [ −o filename ] command [ args ]
DESCRIPTION
lockstat gathers and displays statistics on kernel synchronization objects. lockstat allows you to specify which lock events to watch (for example, spin on adaptive mutex, block on read access to rwlock due to waiting writers, and so forth), how much data to gather for each event, and how to display that data. By default, lockstat monitors all lock contention events, gathers frequency and timing data about those events, and displays that data in order of decreasing frequency so that the most heavily contended locks appear first.
lockstat gathers kernel locking statistics until the specified command completes. For example, to gather statistics for a fixed time interval, specify sleep(1) as the command, as follows:
example# lockstat sleep 5
lockstat relies on the lockstat(7D) driver, an exclusive-access device that modifies the running kernel’s text to intercept events of interest. This imposes a small but measurable overhead on all system activity, so access to the lockstat(7D) driver is restricted to super-user by default. The system administrator may relax this restriction by changing the permissions on /dev/lockstat.
OPTIONS
Event selection options:
−C Watch contention events [on by default].
−E Watch error events [on by default].
−H Watch hold events [off by default].
−A Watch all events. −A is equivalent to −CEH.
−e event list Only watch the specified events. event list is a comma-separated list of events or ranges of events, (for example, 1,4-7,35). Run lockstat with no arguments to get a brief description of all events.
Data gathering options (mutually exclusive):
−b Basic statistics: lock, caller, number of events.
−t Timing: Basic plus timing for all events [default].
−h Histogram: Timing plus time distribution histograms.
−s depth Stack trace: Histogram plus stack traces of events.
Data filtering options:
−n nlocks Maximum number of locks to watch.
−l lock[,size] Only watch lock, which can be specified as a symbolic name or hex address. size defaults to the ELF symbol size or 1 if the symbol size is not available.
−d duration Only watch events longer than duration.
−T Trace (rather than sample) events [off by default].
Data reporting options:
−c Coalesce lock data for lock arrays (for example, pse_mutex[]).
−w Wherever: distinguish events only by lock, not by caller.
−W Whichever: distinguish events only by caller, not by lock.
−R Display rates (events per second) rather than counts.
−p Parsable output format.
−D count Only display the top count events of each type.
−o filename Direct output to filename.
EXAMPLES
Descriptions of the fields from the output of lockstat are listed below.
Count or ops/s Number of times this lock was acquired by this caller, or the rate (times per second) if −R was specified.
indv Percentage of all events represented by this individual event.
cuml Cumulative percentage; a running total of the individuals.
rcnt Average reference count. This will always be 1 for exclusive locks (mutexes, spin locks, rwlocks held as writer) but may be greater than 1 for shared locks (rwlocks held as reader, shared pages, counting semaphores).
spin or nsec Average number of times caller spun trying to get the lock, or average duration of the events in nanoseconds, as appropriate for the event.
Lock Address of the lock.
Caller Address of the caller.
The following example uses lockstat to gather kernel locking statistics for five seconds: example# lockstat sleep 5
Adaptive mutex spin: 513 events
| Count | indv | cuml | rcnt | spin | Lock | Caller |
| ----- | ---- | ---- | ---- | ---- | ---------- | ------------- |
| 99 | 19% | 19% | 1.00 | 194 | 0x6335e5f4 | cv_timedwait+0xac |
| 95 | 19% | 38% | 1.00 | 192 | 0x6335e5f4 | nfs_async_start+0x7c |
| 55 | 11% | 49% | 1.00 | 297 | 0x6335e5f4 | nfs_async_readahead+0xf4 |
| 24 | 5% | 53% | 1.00 | 12 | rt_callout_state | untimeout+0x24 |
| 19 | 4% | 57% | 1.00 | 11 | 0x61325e3c | nfs3_readahead+0x3c |
| 16 | 3% | 60% | 1.00 | 26 | 0x61478554 | nfs3_readahead+0x3c |
| 15 | 3% | 63% | 1.00 | 28 | rt_callout_state | realtime_timeout+0xc |
| 15 | 3% | 66% | 1.00 | 286 | 0x620f0280 | cv_wait_sig_swap+0x1d0 |
| 14 | 3% | 69% | 1.00 | 7 | 0x61325e3c | nfs3_getapage+0xec |
| 11 | 2% | 71% | 1.00 | 264 | pidlock | thread_exit+0x58 |
| 11 | 2% | 73% | 1.00 | 16 | 0x61478554 | nfs_async_start+0x2d0 |
| 10 | 2% | 75% | 1.00 | 58 | fpc_mutex+0x8 | page_list_add+0xb8 |
| 10 | 2% | 77% | 1.00 | 13 | 0x61478554 | nfs_async_readahead+0xa8 |
| 9 | 2% | 79% | 1.00 | 42 | 0x61325e3c | nfs_async_start+0x2d0 |
| 8 | 2% | 80% | 1.00 | 52 | fpc_mutex+0x48 | page_list_add+0xb8 |
| 7 | 1% | 82% | 1.00 | 7 | 0x61478554 | nfs3_getapage+0xec |
| 6 | 1% | 83% | 1.00 | 3 | 0x61325e3c | nfs_async_readahead+0xa8 |
| 6 | 1% | 84% | 1.00 | 63 | fpc_mutex+0x48 | page_get_mnode_freelist+0xa8 |
| 6 | 1% | 85% | 1.00 | 13 | pidlock | cv_wait_sig_swap+0x1d0 |
| 5 | 1% | 86% | 1.00 | 7 | 0x61478554 | nfs3_getapage+0x22c |
| 5 | 1% | 87% | 1.00 | 87 | fpc_mutex+0x28 | page_list_add+0xb8 |
| 5 | 1% | 88% | 1.00 | 30 | 0x61325e3c | nfs3_getapage+0x5a4 |
| 5 | 1% | 89% | 1.00 | 319 | 0x620f0500 | cv_wait_sig_swap+0x1d0 |
| 4 | 1% | 90% | 1.00 | 61 | fpc_mutex+0x8 | page_get_mnode_freelist+0xa8 |
...
FILES
/dev/lockstat lockstat driver
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| Availability | SUNWcsu |
SEE ALSO
attributes(5), lockstat(7D), mutex(9F), rwlock(9F)
NOTES
The lockstat technology is provided on an as-is basis. The format and content of lockstat output reflect the current Solaris kernel implementation and are therefore subject to change in future releases.
SunOS 5.6 — Last change: 26 May 1997