duck.etc.blueprints.dashboard.system_metrics

System metrics service for the Duck Framework dashboard.

Reads live OS-level metrics using the standard library (psutil where available, fallback to /proc on Linux). Each metric getter is wrapped in a try/except so the panel always renders — failures return an error dict that the UI displays as a graceful error placeholder.

No external dependencies are required; psutil is used opportunistically if installed for richer cross-platform data.

Module Contents

Functions

_err	Returns a standardised error dict for unavailable metrics.
get_concurrency_metrics	Returns active thread count and process information for the current process.
get_cpu_metrics	Returns current CPU utilisation and core count.
get_memory_metrics	Returns virtual memory usage statistics.
get_network_metrics	Returns cumulative network I/O byte counts for the current process.
get_open_files_metrics	Returns the number of open file descriptors for the current process.
get_storage_metrics	Returns disk usage for the largest available real filesystem, avoiding small container overlay / tmpfs mounts.
get_system_metrics	Returns a combined snapshot of all system metrics.

API

duck.etc.blueprints.dashboard.system_metrics._err(label: str, exc: Exception) → dict

Returns a standardised error dict for unavailable metrics.

Parameters:

• label – Human-readable name of the metric that failed.

• exc – The exception that was raised.

Returns:

available (False), label, error.

Return type:

Dict with keys

duck.etc.blueprints.dashboard.system_metrics.get_concurrency_metrics() → dict

Returns active thread count and process information for the current process.

Returns:

available (True), thread_count (int), process_id (int), process_name (str | None). On failure: available (False), label, error.

Return type:

Dict with keys

duck.etc.blueprints.dashboard.system_metrics.get_cpu_metrics() → dict

Returns current CPU utilisation and core count.

Uses psutil.cpu_percent(interval=None) for a non-blocking read of the most recent CPU sample. Falls back to /proc/stat on Linux if psutil is unavailable.

Returns:

available (True), percent (float 0–100), cores_logical (int), cores_physical (int | None), freq_mhz (float | None). On failure: available (False), label, error.

Return type:

Dict with keys

duck.etc.blueprints.dashboard.system_metrics.get_memory_metrics() → dict

Returns virtual memory usage statistics.

Returns:

available (True), total_mb (int), used_mb (int), free_mb (int), percent (float). On failure: available (False), label, error.

Return type:

Dict with keys

duck.etc.blueprints.dashboard.system_metrics.get_network_metrics() → dict

Returns cumulative network I/O byte counts for the current process.

Returns:

available (True), bytes_sent_mb (float), bytes_recv_mb (float), packets_sent (int), packets_recv (int). On failure: available (False), label, error.

Return type:

Dict with keys

duck.etc.blueprints.dashboard.system_metrics.get_open_files_metrics() → dict

Returns the number of open file descriptors for the current process.

Returns:

available (True), open_files (int), soft_limit (int | None), hard_limit (int | None). On failure: available (False), label, error.

Return type:

Dict with keys

duck.etc.blueprints.dashboard.system_metrics.get_storage_metrics() → dict

Returns disk usage for the largest available real filesystem, avoiding small container overlay / tmpfs mounts.

duck.etc.blueprints.dashboard.system_metrics.get_system_metrics() → dict

Returns a combined snapshot of all system metrics.

Each sub-key contains either a metrics dict (available=True) or an error dict (available=False) so callers can render gracefully.

Returns:

cpu, memory, concurrency, open_files, network, storage.

Return type:

Dict with keys