Swift System Metrics

To collect and report process-level metrics (like CPU and memory), create a SystemMetricsMonitor and include it in a ServiceGroup (from swift-service-lifecycle). This ensures the monitor runs periodically as a background service. You must also bootstrap a MetricsSystem implementation to receive the reported data.

import SystemMetrics
import ServiceLifecycle
import Metrics
import Logging

@main
struct Application {
  static func main() async throws {
    let logger = Logger(label: "Application")
    
    // 1. Bootstrap your metrics backend
    let metrics = MyMetricsBackendImplementation()
    MetricsSystem.bootstrap(metrics)

    let service = FooService()
    
    // 2. Create the monitor service
    let systemMetricsMonitor = SystemMetricsMonitor(logger: logger)
    
    // 3. Run the monitor within a ServiceGroup
    let serviceGroup = ServiceGroup(
      services: [service, systemMetricsMonitor],
      gracefulShutdownSignals: [.sigint],
      cancellationSignals: [.sigterm],
      logger: logger
    )

    try await serviceGroup.run()
  }
}

For non-trivial changes that affect the public API, the project uses a lightweight version of the Swift Evolution process. To propose a change, follow these steps:

1. Create an Issue: Ensure there is a GitHub issue for the feature or change you want to propose.
2. Create a Proposal Document: Duplicate the SSM-NNNN.md template, replacing NNNN with the next available proposal number.
3. Fill the Proposal: Link the relevant GitHub issue within your new document and complete the required sections.
4. Submit for Feedback: Open a pull request containing your proposal to solicit feedback from contributors. Including a link to a prototype implementation branch in the PR description is recommended.
5. Review Period: Once a maintainer confirms the proposal is ready, a 7-day review period begins. The review ends when a maintainer marks the proposal as Ready for Implementation or Deferred.
6. Implementation: Ensure an implementation is ready (either in the same PR or a linked separate PR) before merging.
7. Approval: A proposal is considered Approved once the implementation and proposal PRs are merged and any associated feature flags are enabled unconditionally.

You can monitor process-level system metrics by creating an instance of SystemMetricsMonitor. To ensure the monitor runs alongside your application, it is recommended to integrate it into a ServiceGroup from the ServiceLifecycle package.

Before running the monitor, ensure you have bootstrapped a MetricsSystem (e.g., using a custom backend or a standard implementation) so that the collected metrics have a destination.

import SystemMetrics
import ServiceLifecycle
import Metrics
import Logging

@main
struct Application {
  static func main() async throws {
    let logger = Logger(label: "Application")
    let metrics = MyMetricsBackendImplementation()
    MetricsSystem.bootstrap(metrics)

    let service = FooService()
    let systemMetricsMonitor = SystemMetricsMonitor(logger: logger)

    let serviceGroup = ServiceGroup(
      services: [service, systemMetricsMonitor],
      gracefulShutdownSignals: [.sigint],
      cancellationSignals: [.sigterm],
      logger: logger
    )

    try await serviceGroup.run()
  }
}

To ensure the monitor runs as a background service with support for graceful shutdown and UNIX signal handling, integrate it into a ServiceGroup using the Swift Service Lifecycle library.

Include the SystemMetricsMonitor instance in the services array of your ServiceGroup.

import SystemMetrics
import ServiceLifecycle
import Metrics
import Logging

@main
struct Application {
    static func main() async throws {
        let logger = Logger(label: "Application")
        let metrics = MyMetricsBackendImplementation()
        MetricsSystem.bootstrap(metrics)

        let service = FooService()
        let systemMetricsMonitor = SystemMetricsMonitor(logger: logger)

        let serviceGroup = ServiceGroup(
            services: [service, systemMetricsMonitor],
            gracefulShutdownSignals: [.sigint],
            cancellationSignals: [.sigterm],
            logger: logger
        )

        try await serviceGroup.run()
    }
}

To run periodic system metrics collection in the background for the duration of your application, use SystemMetricsMonitor. Because it conforms to the Service protocol from swift-service-lifecycle, the recommended pattern is to include it in a ServiceGroup alongside your application services. This ensures the monitor's lifecycle is managed automatically and it shuts down gracefully with your application.

import SystemMetrics
import ServiceLifecycle
import UnixSignals
import Metrics

@main
struct Application {
    static func main() async throws {
        let logger = Logger(label: "Application")
        let metrics = MyMetricsBackendImplementation()
        MetricsSystem.bootstrap(metrics)

        let service = FooService()
        let systemMetricsMonitor = SystemMetricsMonitor()
        let serviceGroup = ServiceGroup(
            services: [service, systemMetricsMonitor],
            gracefulShutdownSignals: [.sigint],
            cancellationSignals: [.sigterm],
            logger: logger
        )

        try await serviceGroup.run()
    }
}