calculateMemUsageUnixNoCache: subtract total_inactive_file, not cache

The new stat definition corresponds to containerd/CRI and cadvisor.

c1115d4e57/pkg/server/container_stats_list_unix.go (L106-L129)
307d1b1cb3

Fix https://github.com/moby/moby/issues/40727

Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>

cli/command/container/stats_helpers.go

@@ -225,9 +225,27 @@ func calculateNetwork(network map[string]types.NetworkStats) (float64, float64)
 }
 
 // calculateMemUsageUnixNoCache calculate memory usage of the container.
-// Page cache is intentionally excluded to avoid misinterpretation of the output.
+// Cache is intentionally excluded to avoid misinterpretation of the output.
+//
+// On cgroup v1 host, the result is `mem.Usage - mem.Stats["total_inactive_file"]` .
+// On cgroup v2 host, the result is `mem.Usage - mem.Stats["inactive_file"] `.
+//
+// This definition is consistent with cadvisor and containerd/CRI.
+// * https://github.com/google/cadvisor/commit/307d1b1cb320fef66fab02db749f07a459245451
+// * https://github.com/containerd/cri/commit/6b8846cdf8b8c98c1d965313d66bc8489166059a
+//
+// On Docker 19.03 and older, the result was `mem.Usage - mem.Stats["cache"]`.
+// See https://github.com/moby/moby/issues/40727 for the background.
 func calculateMemUsageUnixNoCache(mem types.MemoryStats) float64 {
-	return float64(mem.Usage - mem.Stats["cache"])
+	// cgroup v1
+	if v, isCgroup1 := mem.Stats["total_inactive_file"]; isCgroup1 && v < mem.Usage {
+		return float64(mem.Usage - v)
+	}
+	// cgroup v2
+	if v := mem.Stats["inactive_file"]; v < mem.Usage {
+		return float64(mem.Usage - v)
+	}
+	return float64(mem.Usage)
 }
 
 func calculateMemPercentUnixNoCache(limit float64, usedNoCache float64) float64 {

cli/command/container/stats_helpers_test.go

@@ -10,7 +10,7 @@ import (
 
 func TestCalculateMemUsageUnixNoCache(t *testing.T) {
 	// Given
-	stats := types.MemoryStats{Usage: 500, Stats: map[string]uint64{"cache": 400}}
+	stats := types.MemoryStats{Usage: 500, Stats: map[string]uint64{"total_inactive_file": 400}}
 
 	// When
 	result := calculateMemUsageUnixNoCache(stats)

docs/reference/commandline/stats.md

@@ -25,7 +25,10 @@ The `docker stats` command returns a live data stream for running containers. To
 
 If you want more detailed information about a container's resource usage, use the `/containers/(id)/stats` API endpoint.
 
-> **Note**: On Linux, the Docker CLI reports memory usage by subtracting page cache usage from the total memory usage. The API does not perform such a calculation but rather provides the total memory usage and the amount from the page cache so that clients can use the data as needed.
+> **Note**: On Linux, the Docker CLI reports memory usage by subtracting cache usage from the total memory usage. The API does not perform such a calculation but rather provides the total memory usage and the amount from the cache so that clients can use the data as needed.
+The cache usage is defined as the value of `total_inactive_file` field in the `memory.stat` file on cgroup v1 hosts.
+On Docker 19.03 and older, the cache usage was defined as the value of `cache` field.
+On cgroup v2 hosts, the cache usage is defined as the value of `inactive_file` field.
 
 > **Note**: The `PIDS` column contains the number of processes and kernel threads created by that container. Threads is the term used by Linux kernel. Other equivalent terms are "lightweight process" or "kernel task", etc. A large number in the `PIDS` column combined with a small number of processes (as reported by `ps` or `top`) may indicate that something in the container is creating many threads.