Add CPU usage to reported metrics (#26)

Author: gjcairo

Sources/SystemMetrics/SystemMetrics.swift

@@ -2,7 +2,7 @@
 //
 // This source file is part of the Swift Metrics API open source project
 //
-// Copyright (c) 2018-2020 Apple Inc. and the Swift Metrics API project authors
+// Copyright (c) 2018-2023 Apple Inc. and the Swift Metrics API project authors
 // Licensed under Apache License v2.0
 //
 // See LICENSE.txt for license information
@@ -69,6 +69,7 @@ extension MetricsSystem {
                 Gauge(label: self.labels.label(for: \.cpuSecondsTotal), dimensions: self.dimensions).record(metrics.cpuSeconds)
                 Gauge(label: self.labels.label(for: \.maxFileDescriptors), dimensions: self.dimensions).record(metrics.maxFileDescriptors)
                 Gauge(label: self.labels.label(for: \.openFileDescriptors), dimensions: self.dimensions).record(metrics.openFileDescriptors)
+                Gauge(label: self.labels.label(for: \.cpuUsage), dimensions: self.dimensions).record(metrics.cpuUsage)
             }))
 
             self.timer.schedule(deadline: .now() + self.timeInterval, repeating: self.timeInterval)
@@ -145,6 +146,8 @@ public enum SystemMetrics {
         let maxFileDescriptors: String
         /// Number of open file descriptors.
         let openFileDescriptors: String
+        /// CPU usage percentage.
+        let cpuUsage: String
 
         /// Create a new `Labels` instance.
         ///
@@ -156,14 +159,25 @@ public enum SystemMetrics {
         ///     - cpuSecondsTotal: Total user and system CPU time spent in seconds.
         ///     - maxFds: Maximum number of open file descriptors.
         ///     - openFds: Number of open file descriptors.
-        public init(prefix: String, virtualMemoryBytes: String, residentMemoryBytes: String, startTimeSeconds: String, cpuSecondsTotal: String, maxFds: String, openFds: String) {
+        ///     - cpuUsage: Total CPU usage percentage.
+        public init(
+            prefix: String,
+            virtualMemoryBytes: String,
+            residentMemoryBytes: String,
+            startTimeSeconds: String,
+            cpuSecondsTotal: String,
+            maxFds: String,
+            openFds: String,
+            cpuUsage: String
+        ) {
             self.prefix = prefix
             self.virtualMemoryBytes = virtualMemoryBytes
             self.residentMemoryBytes = residentMemoryBytes
             self.startTimeSeconds = startTimeSeconds
             self.cpuSecondsTotal = cpuSecondsTotal
             self.maxFileDescriptors = maxFds
             self.openFileDescriptors = openFds
+            self.cpuUsage = cpuUsage
         }
 
         func label(for keyPath: KeyPath<Labels, String>) -> String {
@@ -173,7 +187,7 @@ public enum SystemMetrics {
 
     /// System Metric data.
     ///
-    /// The current list of metrics exposed is taken from the Prometheus Client Library Guidelines
+    /// The current list of metrics exposed is a superset of the Prometheus Client Library Guidelines:
     /// https://prometheus.io/docs/instrumenting/writing_clientlibs/#standard-and-runtime-collectors
     public struct Data {
         /// Virtual memory size in bytes.
@@ -188,82 +202,121 @@ public enum SystemMetrics {
         var maxFileDescriptors: Int
         /// Number of open file descriptors.
         var openFileDescriptors: Int
+        /// CPU usage percentage.
+        var cpuUsage: Double
     }
 
     #if os(Linux)
-    internal static func linuxSystemMetrics() -> SystemMetrics.Data? {
-        /// Minimal file reading implementation so we don't have to depend on Foundation.
-        /// Designed only for the narrow use case of this library, reading `/proc/self/stat`.
-        final class CFile {
-            let path: String
+    /// Minimal file reading implementation so we don't have to depend on Foundation.
+    /// Designed only for the narrow use case of this library.
+    final class CFile {
+        let path: String
 
-            private var file: UnsafeMutablePointer<FILE>?
+        private var file: UnsafeMutablePointer<FILE>?
 
-            init(_ path: String) {
-                self.path = path
-            }
+        init(_ path: String) {
+            self.path = path
+        }
 
-            deinit {
-                assert(self.file == nil)
-            }
+        deinit {
+            assert(self.file == nil)
+        }
 
-            func open() {
-                guard let f = fopen(path, "r") else {
-                    return
-                }
-                self.file = f
+        func open() {
+            guard let f = fopen(path, "r") else {
+                return
             }
+            self.file = f
+        }
 
-            func close() {
-                if let f = self.file {
-                    self.file = nil
-                    let success = fclose(f) == 0
-                    assert(success)
-                }
+        func close() {
+            if let f = self.file {
+                self.file = nil
+                let success = fclose(f) == 0
+                assert(success)
             }
+        }
 
-            func readLine() -> String? {
-                guard let f = self.file else {
-                    return nil
-                }
-                var buff = [CChar](repeating: 0, count: 1024)
-                let hasNewLine = buff.withUnsafeMutableBufferPointer { ptr -> Bool in
-                    guard fgets(ptr.baseAddress, Int32(ptr.count), f) != nil else {
-                        if feof(f) != 0 {
-                            return false
-                        } else {
-                            preconditionFailure("Error reading line")
-                        }
+        func readLine() -> String? {
+            guard let f = self.file else {
+                return nil
+            }
+            var buff = [CChar](repeating: 0, count: 1024)
+            let hasNewLine = buff.withUnsafeMutableBufferPointer { ptr -> Bool in
+                guard fgets(ptr.baseAddress, Int32(ptr.count), f) != nil else {
+                    if feof(f) != 0 {
+                        return false
+                    } else {
+                        preconditionFailure("Error reading line")
                     }
-                    return true
-                }
-                if !hasNewLine {
-                    return nil
                 }
-                return String(cString: buff)
+                return true
             }
+            if !hasNewLine {
+                return nil
+            }
+            return String(cString: buff)
+        }
 
-            func readFull() -> String {
-                var s = ""
-                func loop() -> String {
-                    if let l = readLine() {
-                        s += l
-                        return loop()
-                    }
-                    return s
+        func readFull() -> String {
+            var s = ""
+            func loop() -> String {
+                if let l = readLine() {
+                    s += l
+                    return loop()
                 }
-                return loop()
+                return s
             }
+            return loop()
         }
+    }
 
-        let ticks = _SC_CLK_TCK
+    /// A type that can calculate CPU usage for a given process.
+    ///
+    /// CPU usage is calculated as the number of CPU ticks used by this process between measurements.
+    /// - Note: the first measurement will be calculated since the process' start time, since there's no
+    /// previous measurement to take as reference.
+    private struct CPUUsageCalculator {
+        /// The number of ticks after system boot that the last CPU usage stat was taken.
+        private var previousTicksSinceSystemBoot: Int = 0
+        /// The number of ticks the process actively used the CPU, as of the previous CPU usage measurement.
+        private var previousCPUTicks: Int = 0
+
+        mutating func getUsagePercentage(ticksSinceSystemBoot: Int, cpuTicks: Int) -> Double {
+            defer {
+                self.previousTicksSinceSystemBoot = ticksSinceSystemBoot
+                self.previousCPUTicks = cpuTicks
+            }
+            let ticksBetweenMeasurements = ticksSinceSystemBoot - self.previousTicksSinceSystemBoot
+            let cpuTicksBetweenMeasurements = cpuTicks - self.previousCPUTicks
+            return Double(cpuTicksBetweenMeasurements) * 100 / Double(ticksBetweenMeasurements)
+        }
+    }
 
-        let file = CFile("/proc/self/stat")
-        file.open()
+    private static let systemStartTimeInSecondsSinceEpoch: Int? = {
+        let systemStatFile = CFile("/proc/stat")
+        systemStatFile.open()
         defer {
-            file.close()
+            systemStatFile.close()
         }
+        while let line = systemStatFile.readLine() {
+            if line.starts(with: "btime"),
+               let systemUptimeInSecondsSinceEpochString = line
+               .split(separator: " ")
+               .last?
+               .split(separator: "\n")
+               .first,
+               let systemUptimeInSecondsSinceEpoch = Int(systemUptimeInSecondsSinceEpochString)
+            {
+                return systemUptimeInSecondsSinceEpoch
+            }
+        }
+        return nil
+    }()
 
+    private static var cpuUsageCalculator = CPUUsageCalculator()
+
+    internal static func linuxSystemMetrics() -> SystemMetrics.Data? {
         enum StatIndices {
             static let virtualMemoryBytes = 20
             static let residentMemoryBytes = 21
@@ -272,8 +325,26 @@ public enum SystemMetrics {
             static let stimeTicks = 12
         }
 
+        let ticks = _SC_CLK_TCK
+
+        let statFile = CFile("/proc/self/stat")
+        statFile.open()
+        defer {
+            statFile.close()
+        }
+
+        let uptimeFile = CFile("/proc/uptime")
+        uptimeFile.open()
+        defer {
+            uptimeFile.close()
+        }
+
+        // Read both files as close as possible to each other to get an accurate CPU usage metric.
+        let statFileContents = statFile.readFull()
+        let uptimeFileContents = uptimeFile.readFull()
+
         guard
-            let statString = file.readFull()
+            let statString = statFileContents
             .split(separator: ")")
             .last
         else { return nil }
@@ -288,11 +359,25 @@ public enum SystemMetrics {
             let stimeTicks = Int(stats[safe: StatIndices.stimeTicks])
         else { return nil }
         let residentMemoryBytes = rss * _SC_PAGESIZE
-        let startTimeSeconds = startTimeTicks / ticks
-        let cpuSeconds = (utimeTicks / ticks) + (stimeTicks / ticks)
+        let processStartTimeInSeconds = startTimeTicks / ticks
+        let cpuTicks = utimeTicks + stimeTicks
+        let cpuSeconds = cpuTicks / ticks
 
-        var _rlim = rlimit()
+        guard let systemStartTimeInSecondsSinceEpoch = SystemMetrics.systemStartTimeInSecondsSinceEpoch else {
+            return nil
+        }
+        let startTimeInSecondsSinceEpoch = systemStartTimeInSecondsSinceEpoch + processStartTimeInSeconds
+
+        var cpuUsage: Double = 0
+        if cpuTicks > 0 {
+            guard let uptimeString = uptimeFileContents.split(separator: " ").first,
+                  let uptimeSeconds = Float(uptimeString)
+            else { return nil }
+            let uptimeTicks = Int(ceilf(uptimeSeconds)) * ticks
+            cpuUsage = SystemMetrics.cpuUsageCalculator.getUsagePercentage(ticksSinceSystemBoot: uptimeTicks, cpuTicks: cpuTicks)
+        }
 
+        var _rlim = rlimit()
         guard withUnsafeMutablePointer(to: &_rlim, { ptr in
             getrlimit(__rlimit_resource_t(RLIMIT_NOFILE.rawValue), ptr) == 0
         }) else { return nil }
@@ -309,10 +394,11 @@ public enum SystemMetrics {
         return .init(
             virtualMemoryBytes: virtualMemoryBytes,
             residentMemoryBytes: residentMemoryBytes,
-            startTimeSeconds: startTimeSeconds,
+            startTimeSeconds: startTimeInSecondsSinceEpoch,
             cpuSeconds: cpuSeconds,
             maxFileDescriptors: maxFileDescriptors,
-            openFileDescriptors: openFileDescriptors
+            openFileDescriptors: openFileDescriptors,
+            cpuUsage: cpuUsage
         )
     }
 

Tests/SystemMetricsTests/SystemMetricsTests.swift

@@ -33,21 +33,41 @@ class SystemMetricsTest: XCTestCase {
         XCTAssertNotNil(metrics.cpuSeconds)
         XCTAssertNotNil(metrics.maxFileDescriptors)
         XCTAssertNotNil(metrics.openFileDescriptors)
+        XCTAssertNotNil(metrics.cpuUsage)
     }
 
     func testSystemMetricsLabels() throws {
-        let labels = SystemMetrics.Labels(prefix: "pfx+", virtualMemoryBytes: "vmb", residentMemoryBytes: "rmb", startTimeSeconds: "sts", cpuSecondsTotal: "cpt", maxFds: "mfd", openFds: "ofd")
+        let labels = SystemMetrics.Labels(
+            prefix: "pfx+",
+            virtualMemoryBytes: "vmb",
+            residentMemoryBytes: "rmb",
+            startTimeSeconds: "sts",
+            cpuSecondsTotal: "cpt",
+            maxFds: "mfd",
+            openFds: "ofd",
+            cpuUsage: "cpu"
+        )
 
         XCTAssertEqual(labels.label(for: \.virtualMemoryBytes), "pfx+vmb")
         XCTAssertEqual(labels.label(for: \.residentMemoryBytes), "pfx+rmb")
         XCTAssertEqual(labels.label(for: \.startTimeSeconds), "pfx+sts")
         XCTAssertEqual(labels.label(for: \.cpuSecondsTotal), "pfx+cpt")
         XCTAssertEqual(labels.label(for: \.maxFileDescriptors), "pfx+mfd")
         XCTAssertEqual(labels.label(for: \.openFileDescriptors), "pfx+ofd")
+        XCTAssertEqual(labels.label(for: \.cpuUsage), "pfx+cpu")
     }
 
     func testSystemMetricsConfiguration() throws {
-        let labels = SystemMetrics.Labels(prefix: "pfx_", virtualMemoryBytes: "vmb", residentMemoryBytes: "rmb", startTimeSeconds: "sts", cpuSecondsTotal: "cpt", maxFds: "mfd", openFds: "ofd")
+        let labels = SystemMetrics.Labels(
+            prefix: "pfx_",
+            virtualMemoryBytes: "vmb",
+            residentMemoryBytes: "rmb",
+            startTimeSeconds: "sts",
+            cpuSecondsTotal: "cpt",
+            maxFds: "mfd",
+            openFds: "ofd",
+            cpuUsage: "cpu"
+        )
         let dimensions = [("app", "example"), ("environment", "production")]
         let configuration = SystemMetrics.Configuration(pollInterval: .microseconds(123_456_789), labels: labels, dimensions: dimensions)
 
@@ -61,6 +81,7 @@ class SystemMetricsTest: XCTestCase {
         XCTAssertEqual(configuration.labels.label(for: \.cpuSecondsTotal), "pfx_cpt")
         XCTAssertEqual(configuration.labels.label(for: \.maxFileDescriptors), "pfx_mfd")
         XCTAssertEqual(configuration.labels.label(for: \.openFileDescriptors), "pfx_ofd")
+        XCTAssertEqual(configuration.labels.label(for: \.cpuUsage), "pfx_cpu")
 
         XCTAssertTrue(configuration.dimensions.contains(where: { $0 == ("app", "example") }))
         XCTAssertTrue(configuration.dimensions.contains(where: { $0 == ("environment", "production") }))