# Role of the Metrics Service in vorssaint-utils: System Monitoring Architecture

> Discover the Metrics service in vorssaint-utils. Learn how it gathers, normalizes, and presents system statistics for intuitive monitoring, respecting your display preferences.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: architecture
- Published: 2026-09-08

---

**The Metrics service in vorssaint-utils collects platform-specific system statistics (CPU load, temperature, memory, and disk usage), normalizes them into consumable snapshots, and feeds these values to the menu-bar UI layer while respecting user preferences for display formatting.**

The vorssaint-utils repository provides macOS system utilities, and its Metrics service forms the backbone of real-time performance monitoring displayed in the menu bar. This service abstracts low-level system sampling into a testable pipeline that drives the UI rendering layer.

## Core Responsibilities of the Metrics Service

The Metrics service operates as a data collection and distribution layer between system APIs and the user interface. Its architecture separates raw data acquisition from presentation logic.

### Sampling System Metrics with DiskSampler

Concrete metric collection is implemented via specialized sampler classes located in the Services directory. In [`Sources/Vorssaint/Services/Metrics/DiskSampler.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Metrics/DiskSampler.swift), the service implements platform-specific logic to query disk-space statistics. These samplers return raw numeric values that the service aggregates into a unified data model.

Each sampler follows a consistent interface pattern, allowing the core system to poll disparate metrics (CPU, memory, temperature) through a standardized API. The samplers throttle their collection frequency to prevent excessive CPU load during continuous monitoring.

### Aggregating Data via Monitor Snapshots

The service exposes current system state through a `snapshot` property on the monitor instance. When the UI layer requests updated metrics, it accesses `monitor.snapshot`, which returns a normalized dictionary of values ready for rendering.

This snapshot pattern decouples the UI from sampling latency; the Metrics service handles caching and refresh timing internally while presenting a synchronous interface to controllers.

## Integrating Metrics into the Menu Bar Interface

Beyond data collection, the Metrics service determines how quantitative information renders in the macOS menu bar based on runtime configuration.

### Rendering Strategy in StatusItemController

In [`Sources/Vorssaint/App/StatusItemController.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/App/StatusItemController.swift), the controller consumes metric snapshots and constructs `NSStatusItem` instances. The service supports two display modes controlled by the `menuBarSeparateMetrics` preference:

- **Combined mode**: Aggregates all metrics into a single status item string
- **Separate mode**: Creates distinct status items for each active metric (CPU, memory, disk)

The controller consults the snapshot to determine which metrics are currently available before instantiating the corresponding UI elements.

### Handling User Preferences

Display behavior is governed by keys defined in [`Sources/Vorssaint/Core/Defaults.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Defaults.swift). The service checks `menuBarHideIconWithMetrics` to determine whether to suppress the application icon when metric items are visible, and `menuBarSeparateMetrics` to select the layout strategy.

The [`Sources/Vorssaint/App/MenuBarSpacingSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/App/MenuBarSpacingSupport.swift) file implements the logic that calculates required spacing and visibility states based on these defaults, ensuring the menu bar remains uncluttered according to user configuration.

## Code Implementation Examples

### Accessing Snapshot Data

To retrieve current system metrics for display or logging:

```swift
let snapshot = monitor.snapshot
let cpuLoad = snapshot["cpu"] ?? 0.0
let memoryPressure = snapshot["memory"] ?? 0.0
MenuBarMetricsPreview(snapshot: snapshot)

```

### Checking Display Preferences

Before rendering status items, validate user configuration:

```swift
let defaults = UserDefaults.standard
let hideIcon = defaults.bool(forKey: "menuBarHideIconWithMetrics")
let separate = defaults.bool(forKey: "menuBarSeparateMetrics")

if separate {
    StatusItemController.renderSeparateMetrics(snapshot, hideIcon: hideIcon)
} else {
    StatusItemController.renderCombinedMetrics(snapshot, hideIcon: hideIcon)
}

```

### Implementing a Custom Sampler

To extend the Metrics service with additional hardware sensors:

```swift
struct TemperatureSampler {
    func sample() -> [String: Double] {
        // Platform-specific IOKit or SMC calls
        return ["cpu_temp": 65.4, "gpu_temp": 58.2]
    }
}

```

## Testing the Metrics Pipeline

The [`Tests/MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift) file validates the entire data flow from sampler to UI. Unit tests verify that:

- `DiskSampler` returns valid numeric ranges for used and available space
- The snapshot aggregation correctly combines multiple sampler outputs
- User defaults keys properly influence rendering decisions in `StatusItemController`

These tests ensure that platform-specific code in `Sources/Vorssaint/Services/Metrics/` correctly integrates with the generic UI abstractions in `Sources/Vorssaint/App/`.

## Summary

- The **Metrics service** bridges system-level data collection and menu-bar UI rendering in vorssaint-utils.
- **[`DiskSampler.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/DiskSampler.swift)** and related samplers handle platform-specific metric acquisition while throttling CPU usage.
- The **`monitor.snapshot`** API provides a normalized, synchronous interface for UI controllers to access current system state.
- **`StatusItemController`** and **`MenuBarSpacingSupport`** translate raw metrics into menu-bar items while respecting `menuBarHideIconWithMetrics` and `menuBarSeparateMetrics` preferences.
- **[`MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/MetricsTests.swift)** ensures sampler accuracy and correct integration with user defaults.

## Frequently Asked Questions

### What types of metrics does the Metrics service collect?

The Metrics service collects CPU load, memory pressure, temperature readings, and disk usage statistics. Each metric type is implemented as a separate sampler class under `Sources/Vorssaint/Services/Metrics/`, such as [`DiskSampler.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/DiskSampler.swift) for storage statistics.

### How does vorssaint-utils handle user preferences for menu bar display?

The service reads `menuBarHideIconWithMetrics` and `menuBarSeparateMetrics` from [`Sources/Vorssaint/Core/Defaults.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/Defaults.swift) via `UserDefaults`. These booleans determine whether the app icon hides when metrics are shown and whether metrics render as separate status items or a combined string.

### Where is the disk usage sampling logic implemented?

Disk usage sampling is implemented in [`Sources/Vorssaint/Services/Metrics/DiskSampler.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Metrics/DiskSampler.swift). This file contains the platform-specific code that queries available and used storage space, returning values that the Metrics service incorporates into the unified snapshot.

### How is the Metrics service tested?

[`Tests/MetricsTests.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tests/MetricsTests.swift) contains unit tests that validate sampler output ranges, snapshot aggregation logic, and the interaction between user defaults and `StatusItemController` rendering decisions. This ensures that hardware-specific sampling code correctly drives the UI layer.