Documentation
¶
Overview ¶
Package lockmetrics provides an instrumented sync.RWMutex that emits Prometheus metrics on every lock acquisition and release.
Usage:
mu := lockmetrics.New("s3.global")
mu.Lock("DeleteBucket")
defer mu.Unlock()
mu.RLock("ListBuckets")
defer mu.RUnlock()
Metrics emitted:
- gopherstack_lock_wait_seconds – histogram of time waiting to acquire
- gopherstack_lock_hold_seconds – histogram of write-lock hold duration
- gopherstack_lock_active_writers – gauge: current write-lock holders (0 or 1)
- gopherstack_lock_active_readers – gauge: current read-lock holders
- gopherstack_lock_write_held_seconds – live gauge: seconds the write lock has been held right now (emitted only while held)
- gopherstack_lock_write_waiters – live gauge: goroutines currently blocked waiting to acquire the write lock
- gopherstack_lock_read_waiters – live gauge: goroutines currently blocked waiting to acquire the read lock
Deadlock detection: if gopherstack_lock_write_waiters (or read_waiters) is > 0 and gopherstack_lock_write_held_seconds keeps climbing, a goroutine is stuck waiting for a lock that is never released.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type RWMutex ¶
type RWMutex struct {
// contains filtered or unexported fields
}
RWMutex is a drop-in replacement for sync.RWMutex that records Prometheus metrics on every Lock/RLock call.
The zero value is not usable; always create via New.
func New ¶
New creates a new RWMutex. The name appears as the labelLock label in all emitted metrics and should be a stable, human-readable identifier (e.g. "s3", "ddb.table.users").
func (*RWMutex) Close ¶
func (m *RWMutex) Close()
Close removes the RWMutex from the global metrics registry. It must be called when the mutex is no longer needed (e.g. on table/bucket deletion) to prevent memory leaks and performance degradation.
func (*RWMutex) GetLockStatus ¶
GetLockStatus returns whether the write lock is currently held, and the number of write and read waiters. This can be used to detect potential deadlocks.
func (*RWMutex) Lock ¶
Lock acquires the exclusive write lock. op is the name of the calling operation (e.g. "DeleteBucket") and is recorded in metrics so lock contention can be attributed to specific callers.
func (*RWMutex) RLock ¶
RLock acquires the shared read lock. op names the calling operation and is recorded in the wait-time histogram.
func (*RWMutex) ReadWaiters ¶
ReadWaiters returns the current number of goroutines blocked waiting for the read lock. Exposed for testing; the Prometheus Collector is the primary consumer in production.
func (*RWMutex) Unlock ¶
func (m *RWMutex) Unlock()
Unlock releases the exclusive write lock. The operation name recorded during Lock is used to attribute the hold-duration histogram.
func (*RWMutex) WriteWaiters ¶
WriteWaiters returns the current number of goroutines blocked waiting for the write lock. Exposed for testing; the Prometheus Collector is the primary consumer in production.
Source Files