A Swift library for reporting process-level system metrics (memory, CPU, file descriptors) to Swift Metrics.
- 📚 Documentation is available on the Swift Package Index.
- 💻 Examples are available in the Examples directory.
- 🚀 Contributions are welcome, please see CONTRIBUTING.md.
- 🪪 License is Apache 2.0, repeated in LICENSE.
- 🔒 Security issues should be reported via the security process.
Swift System Metrics provides a type that periodically collects process-level system metrics and reports them to the Swift Metrics factory.
This package is designed to be run in tools and applications directly and is not expected to be used from libraries. If you'd like to report additional metrics from your library, use Swift Metrics directly.
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 use in your code:
import SystemMetrics
import ServiceLifecycle
import Metrics
import Logging
@main
struct Application {
static func main() async throws {
// Create a logger, or use one of the existing loggers
let logger = Logger(label: "Application")
let metrics = MyMetricsBackendImplementation()
MetricsSystem.bootstrap(metrics)
let service = FooService()
// Create the monitor
let systemMetricsMonitor = SystemMetricsMonitor(logger: logger)
// Create the service
let serviceGroup = ServiceGroup(
services: [service, systemMetricsMonitor],
gracefulShutdownSignals: [.sigint],
cancellationSignals: [.sigterm],
logger: logger
)
try await serviceGroup.run()
}
}The monitor collects and reports the following metrics as gauges:
- Virtual Memory: Total virtual memory, in bytes, that the process allocates.
- Metric name:
process_virtual_memory_bytes
- Metric name:
- Resident Memory: Physical memory, in bytes, that the process currently uses.
- Metric name:
process_resident_memory_bytes
- Metric name:
- Start Time: Process start time, in seconds, since UNIX epoch.
- Metric name:
process_start_time_seconds
- Metric name:
- CPU Time: Cumulative CPU time the process consumes, in seconds.
- Metric name:
process_cpu_seconds_total
- Metric name:
- Max File Descriptors: The maximum number of file descriptors the process can open.
- Metric name:
process_max_fds
- Metric name:
- Open File Descriptors: The number of file descriptors the process currently has open.
- Metric name:
process_open_fds
- Metric name:
- Thread Count: The number of threads in the process.
- Metric name:
process_thread_count
- Metric name:
- Minor Page Faults: The number of minor page faults (no disk I/O required).
- Metric name:
process_page_faults_minor_total
- Metric name:
- Major Page Faults: The number of major page faults (required disk I/O).
- Metric name:
process_page_faults_major_total
- Metric name:
If your metrics backend expects different label names, use MappingMetricsFactory from Swift Metrics to rename labels
without modifying the library itself. See the
Getting Started
guide for a complete example.
The library is supported on macOS and Linux.
| Component | macOS | Linux |
|---|---|---|
| SystemMetrics | ✅ 13+ | ✅ |
Comprehensive documentation is hosted on the Swift Package Index.