Skip to content

Commit d2e6ee5

Browse files
authored
Add System Metrics docs to README (#5)
1 parent d1ac288 commit d2e6ee5

File tree

1 file changed

+51
-1
lines changed

1 file changed

+51
-1
lines changed

README.md

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,4 +40,54 @@ Swift Metrics Extras ships the following extra modules:
4040

4141
### System Metrics
4242

43-
TODO: some docs about the system metrics.
43+
The System Metrics package provides default process metrics for applications. The following metrics are exposed:
44+
45+
- Virtual memory in Bytes.
46+
- Resident memory in Bytes.
47+
- Application start time in Seconds.
48+
- Total CPU seconds.
49+
- Maximum number of file descriptors.
50+
- Number of file descriptors currently in use.
51+
52+
***NOTE:*** Currently these metrics are only implemented on Linux platforms, and not on Darwin or Windows.
53+
54+
#### Using System Metrics
55+
56+
After [adding swift-metrics-extras as a dependency](#adding-the-dependency) you can import the `SystemMetrics` module.
57+
58+
```swift
59+
import SystemMetrics
60+
```
61+
62+
This makes the System Metrics API available. This adds a new method to `MetricsSystem` called `bootstrapWithSystemMetrics`. Calling this method will call `MetricsSystem.bootstrap` as well as bootstrapping System Metrics.
63+
64+
`bootstrapWithSystemMetrics` takes a `SystemMetrics.Configuration` object to configure the system metrics. The config has the following properties:
65+
66+
- interval: The interval at which SystemMetrics are being calculated & exported.
67+
- dataProvider: A closure returing `SystemMetrics.Data?`. When `nil` no metrics are exported (the default on non-linux platforms). `SystemMetrics.Data` holds all the values mentioned above.
68+
- labels: `SystemMetrics.Labels` hold a string label for each of the above mentioned metrics that will be used for the metric labels, along with a prefix that will be used for all above mentioned metrics.
69+
70+
Swift Metrics backend implementations are encouraged to provide static extensions to `SystemMetrics.Configuration` that fit the requirements of their specific backends. For example:
71+
```swift
72+
public extension SystemMetrics.Configuration {
73+
/// `SystemMetrics.Configuration` with Prometheus style labels.
74+
///
75+
/// For more information see `SystemMetrics.Configuration`
76+
static let prometheus = SystemMetrics.Configuration(
77+
labels: .init(
78+
prefix: "process_",
79+
virtualMemoryBytes: "virtual_memory_bytes",
80+
residentMemoryBytes: "resident_memory_bytes",
81+
startTimeSeconds: "start_time_seconds",
82+
cpuSecondsTotal: "cpu_seconds_total",
83+
maxFds: "max_fds",
84+
openFds: "open_fds"
85+
)
86+
)
87+
}
88+
```
89+
This allows end users to add System Metrics like this:
90+
91+
```swift
92+
MetricsSystem.bootstrapWithSystemMetrics(myPrometheusInstance, config: .prometheus)
93+
```

0 commit comments

Comments
 (0)