Fix Linux memory and CPU metrics derived from procfs (#46)

### Motivation

This package provides some system metrics on Linux derived from procfs.
These include CPU and memory metrics. The values returned from
`/proc/self/stat` need to be combined with system values. For example,
some values are returned in clock ticks or memory pages, so need to be
divided appropriately according to the system configuration for clock
ticks per second or page size, respectively.

Looking at the code, some attempt was made to do this: `_SC_CLK_TCK` and
`_SC_PAGESIZE` were used as divisors.

However, these values are the values of the _option_ parameter used in
the call to `sysconf(3)`, not the results themselves.

To illustrate this, here's a Swift program that prints the option name,
option value, and the result of `sysconf(optionValue)`:

```swift
#if !os(Linux)
import Foundation
print("error: This tool is only supported on Linux")
exit(1)
#else
import Glibc

for (optionName, optionValue) in [
    ("_SC_ARG_MAX", _SC_ARG_MAX),
    ("_SC_CHILD_MAX", _SC_CHILD_MAX),
    ("_SC_CLK_TCK", _SC_CLK_TCK),
    ("_SC_NGROUPS_MAX", _SC_NGROUPS_MAX),
    ("_SC_OPEN_MAX", _SC_OPEN_MAX),
    ("_SC_STREAM_MAX", _SC_STREAM_MAX),
    ("_SC_TZNAME_MAX", _SC_TZNAME_MAX),
    ("_SC_JOB_CONTROL", _SC_JOB_CONTROL),
    ("_SC_SAVED_IDS", _SC_SAVED_IDS),
    ("_SC_REALTIME_SIGNALS", _SC_REALTIME_SIGNALS),
    ("_SC_PRIORITY_SCHEDULING", _SC_PRIORITY_SCHEDULING),
    ("_SC_TIMERS", _SC_TIMERS),
    ("_SC_ASYNCHRONOUS_IO", _SC_ASYNCHRONOUS_IO),
    ("_SC_PRIORITIZED_IO", _SC_PRIORITIZED_IO),
    ("_SC_SYNCHRONIZED_IO", _SC_SYNCHRONIZED_IO),
    ("_SC_FSYNC", _SC_FSYNC),
    ("_SC_MAPPED_FILES", _SC_MAPPED_FILES),
    ("_SC_MEMLOCK", _SC_MEMLOCK),
    ("_SC_MEMLOCK_RANGE", _SC_MEMLOCK_RANGE),
    ("_SC_MEMORY_PROTECTION", _SC_MEMORY_PROTECTION),
    ("_SC_MESSAGE_PASSING", _SC_MESSAGE_PASSING),
    ("_SC_SEMAPHORES", _SC_SEMAPHORES),
    ("_SC_SHARED_MEMORY_OBJECTS", _SC_SHARED_MEMORY_OBJECTS),
    ("_SC_AIO_LISTIO_MAX", _SC_AIO_LISTIO_MAX),
    ("_SC_AIO_MAX", _SC_AIO_MAX),
    ("_SC_AIO_PRIO_DELTA_MAX", _SC_AIO_PRIO_DELTA_MAX),
    ("_SC_DELAYTIMER_MAX", _SC_DELAYTIMER_MAX),
    ("_SC_MQ_OPEN_MAX", _SC_MQ_OPEN_MAX),
    ("_SC_MQ_PRIO_MAX", _SC_MQ_PRIO_MAX),
    ("_SC_VERSION", _SC_VERSION),
    ("_SC_PAGESIZE", _SC_PAGESIZE),
    ("_SC_RTSIG_MAX", _SC_RTSIG_MAX),
] {
    let actualValue = sysconf(Int32(optionValue))
    print("Option name: \(optionName), Option value: \(optionValue), Actual value: \(actualValue)")
}
#endif
```


```console
% swift sysconf-test/sysconf-test.swift 
Option name: _SC_ARG_MAX, Option value: 0, Actual value: 2097152
Option name: _SC_CHILD_MAX, Option value: 1, Actual value: 63907
Option name: _SC_CLK_TCK, Option value: 2, Actual value: 100
Option name: _SC_NGROUPS_MAX, Option value: 3, Actual value: 65536
Option name: _SC_OPEN_MAX, Option value: 4, Actual value: 65536
Option name: _SC_STREAM_MAX, Option value: 5, Actual value: 16
Option name: _SC_TZNAME_MAX, Option value: 6, Actual value: -1
Option name: _SC_JOB_CONTROL, Option value: 7, Actual value: 1
Option name: _SC_SAVED_IDS, Option value: 8, Actual value: 1
Option name: _SC_REALTIME_SIGNALS, Option value: 9, Actual value: 200809
Option name: _SC_PRIORITY_SCHEDULING, Option value: 10, Actual value: 200809
Option name: _SC_TIMERS, Option value: 11, Actual value: 200809
Option name: _SC_ASYNCHRONOUS_IO, Option value: 12, Actual value: 200809
Option name: _SC_PRIORITIZED_IO, Option value: 13, Actual value: 200809
Option name: _SC_SYNCHRONIZED_IO, Option value: 14, Actual value: 200809
Option name: _SC_FSYNC, Option value: 15, Actual value: 200809
Option name: _SC_MAPPED_FILES, Option value: 16, Actual value: 200809
Option name: _SC_MEMLOCK, Option value: 17, Actual value: 200809
Option name: _SC_MEMLOCK_RANGE, Option value: 18, Actual value: 200809
Option name: _SC_MEMORY_PROTECTION, Option value: 19, Actual value: 200809
Option name: _SC_MESSAGE_PASSING, Option value: 20, Actual value: 200809
Option name: _SC_SEMAPHORES, Option value: 21, Actual value: 200809
Option name: _SC_SHARED_MEMORY_OBJECTS, Option value: 22, Actual value: 200809
Option name: _SC_AIO_LISTIO_MAX, Option value: 23, Actual value: -1
Option name: _SC_AIO_MAX, Option value: 24, Actual value: -1
Option name: _SC_AIO_PRIO_DELTA_MAX, Option value: 25, Actual value: 20
Option name: _SC_DELAYTIMER_MAX, Option value: 26, Actual value: 2147483647
Option name: _SC_MQ_OPEN_MAX, Option value: 27, Actual value: -1
Option name: _SC_MQ_PRIO_MAX, Option value: 28, Actual value: 32768
Option name: _SC_VERSION, Option value: 29, Actual value: 200809
Option name: _SC_PAGESIZE, Option value: 30, Actual value: 4096
Option name: _SC_RTSIG_MAX, Option value: 31, Actual value: 32
```

The results for our metrics were off because we were always using 30 for
page size and 2 for clock ticks.

### Modifications

- Remove the LinuxMain.swift: test discovery is supported on Linux for
all currently supported Swift versions.
- Update the internal documentation regarding the use of
`proc_pid_stat(5)`.
- Use correct value for CPU metrics, obtained from
`sysconf(_SC_CLK_TCK)`, not just `_SC_CLK_TCK`.
- Use correct value for memory metrics, obtained from
`sysconf(_SC_PAGESIZE)`, not just `_SC_PAGESIZE`.
- Write tests for both CPU seconds and RSS memory.

### Result

Fixes #40.

Author: simonjbeaumont

Sources/SystemMetrics/SystemMetrics.swift

@@ -364,6 +364,67 @@ public enum SystemMetrics {
     private static let cpuUsageCalculator = CPUUsageCalculator()
 
     internal static func linuxSystemMetrics() -> SystemMetrics.Data? {
+        /// The current implementation below reads /proc/self/stat. Then,
+        /// presumably to accommodate whitespace in the `comm` field
+        /// without dealing with null-terminated C strings, it splits on the
+        /// closing parenthesis surrounding the value. It then splits the
+        /// remaining string by space, meaning the first element in the
+        /// resulting array, at index 0, refers to the the third field.
+        ///
+        /// Note that the man page documents fields starting at index 1.
+        ///
+        /// ````
+        /// proc_pid_stat(5)     File Formats Manual     proc_pid_stat(5)
+        ///
+        /// ...
+        ///
+        ///  (1) pid  %d
+        ///         The process ID.
+        ///
+        ///  (2) comm  %s
+        ///         The filename of the executable, in parentheses.
+        ///         Strings longer than TASK_COMM_LEN (16) characters
+        ///         (including the terminating null byte) are silently
+        ///         truncated.  This is visible whether or not the
+        ///         executable is swapped out.
+        /// ...
+        ///
+        ///  (14) utime  %lu
+        ///         Amount of time that this process has been scheduled
+        ///         in user mode, measured in clock ticks (divide by
+        ///         sysconf(_SC_CLK_TCK)).  This includes guest time,
+        ///         guest_time (time spent running a virtual CPU, see
+        ///         below), so that applications that are not aware of
+        ///         the guest time field do not lose that time from
+        ///         their calculations.
+        ///
+        ///  (15) stime  %lu
+        ///         Amount of time that this process has been scheduled
+        ///         in kernel mode, measured in clock ticks (divide by
+        ///         sysconf(_SC_CLK_TCK)).
+        ///
+        /// ...
+        ///
+        ///  (22) starttime  %llu
+        ///         The time the process started after system boot.
+        ///         Before Linux 2.6, this value was expressed in
+        ///         jiffies.  Since Linux 2.6, the value is expressed in
+        ///         clock ticks (divide by sysconf(_SC_CLK_TCK)).
+        ///
+        ///         The format for this field was %lu before Linux 2.6.
+        ///
+        ///  (23) vsize  %lu
+        ///         Virtual memory size in bytes.
+        ///         The format for this field was %lu before Linux 2.6.
+        ///
+        ///  (24) rss  %ld
+        ///         Resident Set Size: number of pages the process has
+        ///         in real memory.  This is just the pages which count
+        ///         toward text, data, or stack space.  This does not
+        ///         include pages which have not been demand-loaded in,
+        ///         or which are swapped out.  This value is inaccurate;
+        ///         see /proc/pid/statm below.
+        /// ```
         enum StatIndices {
             static let virtualMemoryBytes = 20
             static let residentMemoryBytes = 21
@@ -372,7 +433,14 @@ public enum SystemMetrics {
             static let stimeTicks = 12
         }
 
-        let ticks = _SC_CLK_TCK
+        /// Some of the metrics from procfs need to be combined with system
+        /// values, which we obtain from sysconf(3). These values do not change
+        /// during the lifetime of the process so we define them as static
+        /// members here.
+        enum SystemConfiguration {
+            static let clockTicksPerSecond = sysconf(Int32(_SC_CLK_TCK))
+            static let pageByteCount = sysconf(Int32(_SC_PAGESIZE))
+        }
 
         let statFile = CFile("/proc/self/stat")
         statFile.open()
@@ -406,10 +474,11 @@ public enum SystemMetrics {
             let utimeTicks = Int(stats[safe: StatIndices.utimeTicks]),
             let stimeTicks = Int(stats[safe: StatIndices.stimeTicks])
         else { return nil }
-        let residentMemoryBytes = rss * _SC_PAGESIZE
-        let processStartTimeInSeconds = startTimeTicks / ticks
+
+        let residentMemoryBytes = rss * SystemConfiguration.pageByteCount
+        let processStartTimeInSeconds = startTimeTicks / SystemConfiguration.clockTicksPerSecond
         let cpuTicks = utimeTicks + stimeTicks
-        let cpuSeconds = cpuTicks / ticks
+        let cpuSeconds = cpuTicks / SystemConfiguration.clockTicksPerSecond
 
         guard let systemStartTimeInSecondsSinceEpoch = SystemMetrics.systemStartTimeInSecondsSinceEpoch else {
             return nil
@@ -422,7 +491,7 @@ public enum SystemMetrics {
                 let uptimeSeconds = Float(uptimeString),
                 uptimeSeconds.isFinite
             else { return nil }
-            let uptimeTicks = Int(ceilf(uptimeSeconds)) * ticks
+            let uptimeTicks = Int(ceilf(uptimeSeconds)) * SystemConfiguration.clockTicksPerSecond
             cpuUsage = SystemMetrics.cpuUsageCalculator.getUsagePercentage(
                 ticksSinceSystemBoot: uptimeTicks,
                 cpuTicks: cpuTicks

Tests/LinuxMain.swift

@@ -109,4 +109,69 @@ class SystemMetricsTest: XCTestCase {
         throw XCTSkip()
         #endif
     }
+
+    func testLinuxResidentMemoryBytes() throws {
+        #if os(Linux)
+
+        let pageByteCount = sysconf(Int32(_SC_PAGESIZE))
+        let allocationSize = 10_000 * pageByteCount
+
+        let warmups = 20
+        for _ in 0..<warmups {
+            let bytes = UnsafeMutableRawBufferPointer.allocate(byteCount: allocationSize, alignment: 1)
+            defer { bytes.deallocate() }
+            bytes.initializeMemory(as: UInt8.self, repeating: .zero)
+        }
+
+        guard let startResidentMemoryBytes = SystemMetrics.linuxSystemMetrics()?.residentMemoryBytes else {
+            XCTFail("Could not get resident memory usage.")
+            return
+        }
+
+        let bytes = UnsafeMutableRawBufferPointer.allocate(byteCount: allocationSize, alignment: 1)
+        defer { bytes.deallocate() }
+        bytes.initializeMemory(as: UInt8.self, repeating: .zero)
+
+        guard let residentMemoryBytes = SystemMetrics.linuxSystemMetrics()?.residentMemoryBytes else {
+            XCTFail("Could not get resident memory usage.")
+            return
+        }
+
+        /// According to the man page for proc_pid_stat(5) the value is
+        /// advertised as inaccurate.  It refers to proc_pid_statm(5), which
+        /// itself states:
+        ///
+        ///     Some of these values are inaccurate because of a kernel-
+        ///     internal scalability optimization.  If accurate values are
+        ///     required, use /proc/pid/smaps or /proc/pid/smaps_rollup
+        ///     instead, which are much slower but provide accurate,
+        ///     detailed information.
+        ///
+        /// Deferring discussion on whether we should extend this package to
+        /// produce these slower-to-retrieve, more-accurate values, we check
+        /// that the RSS value is within 1% of the expected allocation increase.
+        XCTAssertEqual(residentMemoryBytes - startResidentMemoryBytes, allocationSize, accuracy: allocationSize / 100)
+
+        #else
+        throw XCTSkip()
+        #endif
+    }
+
+    func testLinuxCPUSeconds() throws {
+        #if os(Linux)
+
+        let bytes = Array(repeating: UInt8.zero, count: 10)
+        var hasher = Hasher()
+
+        let startTime = Date()
+        while Date().timeIntervalSince(startTime) < 1 {
+            bytes.hash(into: &hasher)
+        }
+
+        XCTAssertEqual(SystemMetrics.linuxSystemMetrics()?.cpuSeconds, 1)
+
+        #else
+        throw XCTSkip()
+        #endif
+    }
 }