Documentation
¶
Overview ¶
Package locks exposes a single HTTP handler at /debug/locks that returns a JSON snapshot of mutex/block contention, current goroutine waiters, and runtime state.
The package is pure stdlib and adds zero instrumentation overhead on any hot path. It reads what the runtime is already collecting:
- runtime.MutexProfile / runtime.BlockProfile — per-call-site cumulative contention and block delay (sampled at the configured rate; sampling cost is paid regardless of whether anyone reads the profile).
- runtime.GoroutineProfile — current stack of every live goroutine, used to count "right now, who is blocked acquiring which lock."
- runtime/metrics — exact counters/histograms (no sampling): cumulative mutex wait, scheduler latency, heap, GC, CPU classes.
All work happens on demand inside the HTTP handler. There is no background goroutine, no accumulator, no per-lock wrapping.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CPUClassSeconds ¶
type CPUClassSeconds struct {
Total float64 `json:"total"`
User float64 `json:"user"`
Idle float64 `json:"idle"`
GCAssist float64 `json:"gc_mark_assist"`
GCDedicated float64 `json:"gc_mark_dedicated"`
Scavenge float64 `json:"scavenge"`
}
CPUClassSeconds are cumulative CPU-seconds by category (since process start).
type GCStats ¶
type GCStats struct {
PausesP50Seconds float64 `json:"pauses_p50_seconds"`
PausesP99Seconds float64 `json:"pauses_p99_seconds"`
CyclesTotal uint64 `json:"cycles_total"`
}
GCStats summarise GC pause distribution (wall time) and cycle count.
type HeapStats ¶
type HeapStats struct {
InUseBytes uint64 `json:"in_use_bytes"`
UnusedBytes uint64 `json:"unused_bytes"`
FreeBytes uint64 `json:"free_bytes"`
ReleasedBytes uint64 `json:"released_bytes"`
StackBytes uint64 `json:"stack_bytes"`
GoalBytes uint64 `json:"goal_bytes"`
AllocsBytes uint64 `json:"allocs_total_bytes"`
}
HeapStats are exact heap memory class breakdowns from runtime/metrics.
type LatencyQuantiles ¶
type LatencyQuantiles struct {
P50 float64 `json:"p50"`
P99 float64 `json:"p99"`
P999 float64 `json:"p999"`
}
LatencyQuantiles describe a distribution by p50/p99/p999.
type RuntimeStats ¶
type RuntimeStats struct {
Goroutines int `json:"goroutines"`
Threads int `json:"threads"`
GOMAXPROCS int `json:"gomaxprocs"`
CgoCalls int64 `json:"cgo_calls_total"`
MutexWaitSeconds float64 `json:"mutex_wait_total_seconds"`
}
RuntimeStats are exact (non-sampled) runtime counters and gauges.
type SampleRates ¶
type SampleRates struct {
MutexFraction int `json:"mutex_fraction"`
CyclesPerSecond int64 `json:"cycles_per_second"`
}
SampleRates exposes the configured sampling rates so consumers know how to interpret cumulative cycle and delay numbers. Mutex profile values scale to nanoseconds via Cycles / CyclesPerSecond * 1e9.
type Site ¶
type Site struct {
Function string `json:"function"`
File string `json:"file"`
Line int `json:"line"`
Count int64 `json:"count"`
Cycles int64 `json:"cycles"`
DelayNs int64 `json:"delay_ns"`
}
Site is one row of mutex/block contention attributed to a user call site (the first non-runtime/non-sync frame walking from the innermost frame outward).
type Snapshot ¶
type Snapshot struct {
CapturedAt time.Time `json:"captured_at"`
UptimeSeconds float64 `json:"uptime_seconds"`
SampleRates SampleRates `json:"sample_rates"`
Runtime RuntimeStats `json:"runtime"`
MutexTopSites []Site `json:"mutex_top_sites"`
BlockTopSites []Site `json:"block_top_sites"`
LiveWaiters map[string]int `json:"live_lock_waiters"`
Heap HeapStats `json:"heap"`
GC GCStats `json:"gc"`
CPUClasses CPUClassSeconds `json:"cpu_classes_seconds"`
SchedLatency LatencyQuantiles `json:"sched_latency_seconds"`
}
Snapshot is the full payload returned by /debug/locks.
Source Files