Swift System Metrics 1.0: A Comprehensive Guide to Process-Level Monitoring

Introduction

Apple has released version 1.0 of Swift System Metrics, a Swift package designed to collect essential process-level system metrics such as CPU utilization time and memory usage. This package runs on both Linux and macOS, offering a unified API across platforms. With this milestone, the API is now stable and ready for production use, making observability accessible to all Swift developers.

Swift System Metrics 1.0: A Comprehensive Guide to Process-Level Monitoring — Source: swift.org

Why Process-Level Monitoring Matters

Monitoring process metrics is crucial for maintaining application health. By tracking resource consumption, you can detect performance issues early, optimize resource usage, and ensure your service remains reliable under varying loads. Swift System Metrics enables you to integrate monitoring into your service with just a few lines of code, ensuring that even the smallest services have production-grade visibility from day one.

Key Features at a Glance

The package collects and reports the following metrics:

CPU utilization time
Virtual and resident memory usage
Open and maximum available file descriptors
Process start time

Additional highlights include:

API-stable public interface — guaranteed backward compatibility
Cross-platform support on Linux and macOS
musl libc compatibility for lightweight Linux environments
Pre-built Grafana dashboard for immediate visualization

How It Fits Into the Swift Ecosystem

Swift System Metrics is part of a larger set of packages that provide an end-to-end metrics solution. Collected metrics are reported to Swift Metrics, a backend-agnostic API that works seamlessly with popular backends like Prometheus and OpenTelemetry. The package also leverages Swift Service Lifecycle to handle process bootstrapping and resource cleanup, making integration with server-side Swift applications straightforward.

Getting Started with Swift System Metrics

Adding the package to your project is simple. Follow these steps:

Add the dependency to your Package.swift:
.package(url: "https://github.com/apple/swift-system-metrics", from: "1.0.0")
Add the library dependency to your target:
.product(name: "SystemMetrics", package: "swift-system-metrics")
Import and integrate in your code as shown below.

import SystemMetrics
import ServiceLifecycle
import Logging
import OTel

@main
struct Application {
  static func main() async throws {
    let logger = Logger(label: "Application")
    var otelConfig = OTel.Configuration.default
    otelConfig.serviceName = "Application"
    let otelService = try OTel.bootstrap(configuration: otelConfig)
    let service = FooService()
    let systemMetricsMonitor = SystemMetricsMonitor(logger: logger)
    let serviceGroup = ServiceGroup(
      services: [otelService, service, systemMetricsMonitor],
      gracefulShutdownSignals: [.sigint],
      cancellationSignals: [.sigterm],
      logger: logger
    )
    try await serviceGroup.run()
  }
}

Migration from swift-metrics-extras

If you were using the previous package swift-metrics-extras, note that it has been renamed to swift-system-metrics to better reflect its purpose. The 1.0 release guarantees a stable API, so porting your code should be straightforward. Consult the package documentation for any breaking changes.

Visualizing Metrics with Grafana

The package includes an example Grafana dashboard configuration that allows you to start visualizing metrics immediately. By pointing Grafana to your metrics backend (e.g., Prometheus), you can create real-time dashboards showing CPU, memory, and file descriptor usage over time. This integration helps you spot trends and anomalies at a glance.

Conclusion

Swift System Metrics 1.0 brings production-grade observability to Swift services on Linux and macOS. With its stable API, cross-platform support, and seamless integration with the Swift ecosystem, it is an essential tool for any developer looking to monitor and optimize their applications. Get started today and gain deeper insights into your process performance.