Implement container stats

This implements statistics gathering across the various components, but
ultimately this is for implementing a new CLI command: `container stats`.
This shows memory usage, cpu usage, network and block i/o and the number
of processes in the container. The new command can inspect stats for 1-N
containers and by default continuously updates in a `top` like stream.

Author: dcantah

Makefile

@@ -176,6 +176,7 @@ integration: init-block
 		$(SWIFT) test -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) --filter TestCLIExecCommand || exit_code=1 ; \
 		$(SWIFT) test -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) --filter TestCLICreateCommand || exit_code=1 ; \
 		$(SWIFT) test -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) --filter TestCLIRunCommand || exit_code=1 ; \
+		$(SWIFT) test -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) --filter TestCLIStatsCommand || exit_code=1 ; \
 		$(SWIFT) test -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) --filter TestCLIImagesCommand || exit_code=1 ; \
 		$(SWIFT) test -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) --filter TestCLIRunBase || exit_code=1 ; \
 		$(SWIFT) test -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) --filter TestCLIBuildBase || exit_code=1 ; \

Sources/ContainerClient/Core/ClientContainer.swift

@@ -314,4 +314,27 @@ extension ClientContainer {
         }
         return fh
     }
+
+    public func stats() async throws -> ContainerStats {
+        let request = XPCMessage(route: .containerStats)
+        request.set(key: .id, value: self.id)
+
+        let client = Self.newXPCClient()
+        do {
+            let response = try await client.send(request)
+            guard let data = response.dataNoCopy(key: .statistics) else {
+                throw ContainerizationError(
+                    .internalError,
+                    message: "no statistics data returned"
+                )
+            }
+            return try JSONDecoder().decode(ContainerStats.self, from: data)
+        } catch {
+            throw ContainerizationError(
+                .internalError,
+                message: "failed to get statistics for container \(self.id)",
+                cause: error
+            )
+        }
+    }
 }

Sources/ContainerClient/Core/ContainerStats.swift

@@ -0,0 +1,61 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025 Apple Inc. and the container project authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//===----------------------------------------------------------------------===//
+
+import Foundation
+
+/// Statistics for a container suitable for CLI display.
+public struct ContainerStats: Sendable, Codable {
+    /// Container ID
+    public var id: String
+    /// Physical memory usage in bytes
+    public var memoryUsageBytes: UInt64
+    /// Memory limit in bytes
+    public var memoryLimitBytes: UInt64
+    /// CPU usage in microseconds
+    public var cpuUsageUsec: UInt64
+    /// Network received bytes (sum of all interfaces)
+    public var networkRxBytes: UInt64
+    /// Network transmitted bytes (sum of all interfaces)
+    public var networkTxBytes: UInt64
+    /// Block I/O read bytes (sum of all devices)
+    public var blockReadBytes: UInt64
+    /// Block I/O write bytes (sum of all devices)
+    public var blockWriteBytes: UInt64
+    /// Number of processes in the container
+    public var numProcesses: UInt64
+
+    public init(
+        id: String,
+        memoryUsageBytes: UInt64,
+        memoryLimitBytes: UInt64,
+        cpuUsageUsec: UInt64,
+        networkRxBytes: UInt64,
+        networkTxBytes: UInt64,
+        blockReadBytes: UInt64,
+        blockWriteBytes: UInt64,
+        numProcesses: UInt64
+    ) {
+        self.id = id
+        self.memoryUsageBytes = memoryUsageBytes
+        self.memoryLimitBytes = memoryLimitBytes
+        self.cpuUsageUsec = cpuUsageUsec
+        self.networkRxBytes = networkRxBytes
+        self.networkTxBytes = networkTxBytes
+        self.blockReadBytes = blockReadBytes
+        self.blockWriteBytes = blockWriteBytes
+        self.numProcesses = numProcesses
+    }
+}

Sources/ContainerClient/Core/XPC+.swift

@@ -115,6 +115,9 @@ public enum XPCKeys: String {
     case volumeLabels
     case volumeReadonly
     case volumeContainerId
+
+    /// Container statistics
+    case statistics
 }
 
 public enum XPCRoute: String {
@@ -132,6 +135,7 @@ public enum XPCRoute: String {
     case containerState
     case containerLogs
     case containerEvent
+    case containerStats
 
     case pluginLoad
     case pluginGet

Sources/ContainerClient/SandboxClient.swift

@@ -273,6 +273,30 @@ extension SandboxClient {
             )
         }
     }
+
+    public func statistics() async throws -> ContainerStats {
+        let request = XPCMessage(route: SandboxRoutes.statistics.rawValue)
+
+        let response: XPCMessage
+        do {
+            response = try await self.client.send(request)
+        } catch {
+            throw ContainerizationError(
+                .internalError,
+                message: "failed to get statistics for container \(self.id)",
+                cause: error
+            )
+        }
+
+        guard let data = response.dataNoCopy(key: .statistics) else {
+            throw ContainerizationError(
+                .internalError,
+                message: "no statistics data returned"
+            )
+        }
+
+        return try JSONDecoder().decode(ContainerStats.self, from: data)
+    }
 }
 
 extension XPCMessage {

Sources/ContainerClient/SandboxRoutes.swift

@@ -39,4 +39,6 @@ public enum SandboxRoutes: String {
     case dial = "com.apple.container.sandbox/dial"
     /// Shutdown the sandbox service process.
     case shutdown = "com.apple.container.sandbox/shutdown"
+    /// Get statistics for the sandbox.
+    case statistics = "com.apple.container.sandbox/statistics"
 }

Sources/ContainerCommands/Application.swift

@@ -59,6 +59,7 @@ public struct Application: AsyncParsableCommand {
                     ContainerLogs.self,
                     ContainerRun.self,
                     ContainerStart.self,
+                    ContainerStats.self,
                     ContainerStop.self,
                 ]
             ),