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

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, 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, 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. 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 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:

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:

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:

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 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 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 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 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 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}