`pumas`

A nvtop-inspired command line tool for Apple Silicon Macs: aka M1, M2, ... This is basically a reimplemented version of [asitop] in Rust.

| Type | Metrics | Available | Comments | | --- | --- | --- | --- | | Utilization | CPU Clusters, GPU, ANE | ✓ | History & current values. ANE util. is measured via power | | Power | CPU, GPU, ANE, total package | ✓ | History & current values | | Frequency | CPU Clusters, GPU | ✓ | Current avg. values | | Frequency | CPU Clusters, GPU | planned | Residency distrib. histograms | | Memory | RAM & swap: size and usage | planned | Apple removed memory bandwidth from powermetrics. |

Pumas uses the built-in powermetrics utility on macOS, which allows access to a variety of hardware performance counters. Note that it requires sudo to run due to powermetrics needing root access to run. Pumas is lightweight and has minimal performance impact.

Pumas only works on Apple Silicon Macs on macOS Monterey and later.

This is a work in progress.

Installation

sh brew install graelo/tap/pumas

sh cargo install pumas

Quickstart

sh sudo pumas run

Use the arrow keys to switch between tabs. Press Esc, q or x to quit.

Screenshots

Overview Tab: global metrics for utilization and power consumption.

Overview

CPU Tab: per-cluster CPU utilization (with short history) and frequency (with short history)

CPU

GPU Tab: GPU utilization (with short history) and frequency (with short history)

GPU

SoC Tab: misc info about the SoC

SoC

Startup:

Startup

Usage

```sh $ pumas --help A power usage monitor for Apple Silicon.

Usage: pumas

Commands: run Run the power usage monitor generate-completion Print a shell completion script to stdout help Print this message or the help of the given subcommand(s)

Options: -h, --help Print help -V, --version Print version ```

Pumas can run in two modes: UI mode (the default) and JSON mode.

```sh $ pumas run --help Run the power usage monitor

Usage: pumas run [OPTIONS]

Options: -i, --sample-rate Update rate (milliseconds): min: 100 [default: 1000] --accent-color Accent color: ASCII code in 0~255 [default: 2] --gauge-bg-color Gauge background color: ASCII code in 0~255 [default: 7] --json Print metrics to stdout as JSON instead of running the UI -h, --help Print help (see more with '--help') -V, --version Print version ```

JSON Mode

In JSON mode, Pumas will stream metrics to stdout as JSON instead of running the UI. You can then pipe the metrics to jq, or create a node-exporter for Prometheus, etc.

For instance, the following command will stream the active ratio of the third CPU core of the first CPU cluster at each sample interval:

sh $ sudo pumas run --json | jq '.metrics.e_clusters[0].cpus[2].active_ratio' 0.04624276980757713 0.11764705926179886 ^C

The JSON schema and an example are available in the schema directory.

Source of metrics

sysinfo crate is used to measure the following:

per-cluster CPU utilization
per-core CPU utilization

powermetrics is used to measure the following:

~~CPU usage via powermetrics~~ (removed: incorrect on M2 chips)
GPU utilization via active residency
CPU & GPU frequency
Package/CPU/GPU/ANE energy consumption

sysctl is used to measure the following:

CPU name
CPU core counts

system_profiler is used to measure the following:

GPU core count

Some information is guesstimate and hardcoded as there doesn't seem to be a official source for it on the system:

CPU, GPU & ANE max power draw

License

Licensed under the [MIT License].

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the MIT license, shall be licensed as MIT, without any additional terms or conditions.