golang/go

doc: runtime/pprof: document mutex profiler stack traces

Open

#44,920 opened on Mar 10, 2021

View on GitHub
 (8 comments) (4 reactions) (0 assignees)Go (19,008 forks)batch import
DocumentationNeedsFixhelp wanted

Repository metrics

Stars
 (133,883 stars)
PR merge metrics
 (No merged PRs in 30d)

Description

The mutex profiler records contention on the Unlock path of locks, so the stack traces in the profiles all appear as Unlock calls rather than the more intuitively expected Lock call [1].

This can be a source of confusion. Here's a Stack Overflow question, and I personally fielded a question about this today.

Our own runtime/pprof docs say nothing about this (in fact, the complete documentation we have for mutex profiles is "mutex - stack traces of holders of contended mutexes"). This should certainly be expanded.

There is a bit of documentation elsewhere online. e.g., @felixge's block profile documentation mentions this property.

Related to #14689.

[1] This also means it isn't possible to directly tell which Lock calls are hottest. In practice I doubt this is an issue as typical mutex use has a unique Unlock call for each unique Lock call. If this were a problem, we could move the recorded stack trace to Lock here (at the expensive of requiring a slot in the sudog to store the stack until we can record the event in Unlock).

Contributor guide