Description
Alex Sarkesian (alextalks) commented:
Recently via #14598 docs were added describing the internal table crdb_internal.cluster_locks, which is intended to visualize locks currently held in the cluster. In the review for the PR, however, I overlooked mentioning an important note on a key limitation of this table, which would be good to rectify in our docs.
This limitation is the first one described in the [original RFC](https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/20220104_cluster_locks.md#limitations] for the feature, which is specifically:
Inability to display replicated locks without waiters. Replicated locks (i.e. write intents) that do not have other operations waiting to acquire them are not tracked in the [in-memory) lock table, despite their being persistent in the storage engine.
Due to the fact that replicated locks (aka write intents) are primarily stored on disk, and are only tracked in-memory when another transaction (or non-transactional operation) encounters them and has to wait, and since crdb_internal.cluster_locks is powered by the locks tracked in memory alone, we do not show replicated locks that do not have waiters via crdb_internal.cluster_locks. This caveat should likely be represented by a note in the documentation of this table, to be sure that it is clear.
It may also be relevant to note that something similar is mentioned in the documentation of Postgres's similar pg_locks feature, which states:
Although tuples are a lockable type of object, information about row-level locks is stored on disk, not in memory, and therefore row-level locks normally do not appear in this view. If a process is waiting for a row-level lock, it will usually appear in the view as waiting for the permanent transaction ID of the current holder of that row lock.
CC'ing @rmloveland as the original author of the docs on this feature, and apologies for not mentioning this previously!
Jira Issue: DOC-5835