{"id":50662228,"url":"https://github.com/srvr-farm/memwatch","last_synced_at":"2026-06-08T03:08:14.104Z","repository":{"id":356172527,"uuid":"1231194964","full_name":"srvr-farm/memwatch","owner":"srvr-farm","description":"Console UI for watching Memory stats","archived":false,"fork":false,"pushed_at":"2026-05-06T22:43:51.000Z","size":51,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-07T00:25:16.760Z","etag":null,"topics":["dmidecode","hardware-monitor","linux","memory-bandwidth","memory-monitor","perf","performance-monitoring","pmu","ram-monitor","ratatui","rust","terminal","tui"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/srvr-farm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-06T18:14:31.000Z","updated_at":"2026-05-06T22:44:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/srvr-farm/memwatch","commit_stats":null,"previous_names":["srvr-farm/memwatch"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/srvr-farm/memwatch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srvr-farm%2Fmemwatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srvr-farm%2Fmemwatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srvr-farm%2Fmemwatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srvr-farm%2Fmemwatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srvr-farm","download_url":"https://codeload.github.com/srvr-farm/memwatch/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srvr-farm%2Fmemwatch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34046065,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dmidecode","hardware-monitor","linux","memory-bandwidth","memory-monitor","perf","performance-monitoring","pmu","ram-monitor","ratatui","rust","terminal","tui"],"created_at":"2026-06-08T03:08:10.108Z","updated_at":"2026-06-08T03:08:14.096Z","avatar_url":"https://github.com/srvr-farm.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# memwatch - Linux Memory Monitor and Bandwidth TUI\n\n`memwatch` is a read-only Linux memory monitor and terminal TUI for RAM usage,\ninstalled DIMM details, memory bandwidth, and the processes using the most\nresident memory. It is useful when you want a lightweight Rust alternative or\ncompanion to tools like `free`, `top`, `htop`, `btop`, `vmstat`, `dmidecode`,\nand `perf`.\n\nThe default mode is an interactive terminal UI. A `--once` mode is also\navailable for scripts, diagnostics, CI logs, and non-interactive environments.\n\n## What You Can Monitor\n\nUse `memwatch` when you want to:\n\n- Monitor Linux memory usage from a terminal, including used, available, free,\n  cache, buffers, swap, dirty pages, and writeback.\n- Find the highest-RSS processes without opening a full process manager.\n- Inspect installed RAM, DIMM slots, memory type, manufacturer, and configured\n  memory speed from SMBIOS/DMI data.\n- Measure memory bandwidth with Linux perf PMU counters when the hardware and\n  kernel expose usable events.\n- Watch Intel uncore IMC memory-controller read/write bandwidth in MiB/s or\n  GiB/s.\n- Debug laptop, desktop, workstation, homelab, and server memory behavior\n  without changing kernel settings or killing processes.\n\n## Features\n\n- Shows total, used, available, free, buffers/cache, swap, dirty, and writeback\n  memory from `/proc/meminfo`.\n- Shows installed memory capacity, DIMM locator, memory type, manufacturer, and\n  configured speed when SMBIOS/DMI data is readable.\n- Measures memory bandwidth from Linux perf PMU counters when supported by the\n  kernel and hardware.\n- Shows aggregate and per-controller read, write, and total bandwidth when those\n  PMU events are available.\n- Lists the highest-RSS processes by scanning `/proc/\u003cpid\u003e/status`.\n- Provides interactive TUI and one-shot plain-text report modes.\n- Degrades to `N/A` values and diagnostics when optional data sources are\n  missing, restricted, or unsupported.\n\n## Keywords\n\nLinux memory monitor, terminal memory monitor, Linux RAM monitor, Rust TUI\nmemory monitor, memory bandwidth monitor, RAM bandwidth monitor, Intel uncore\nIMC monitor, Linux perf PMU, `perf_event_open`, top RSS processes, process memory\nusage, DIMM information, memory speed monitor, SMBIOS memory, DMI memory,\n`dmidecode`, `/proc/meminfo`, `/proc` process monitor.\n\n## Quick Start\n\nRun from the repository without installing:\n\n```sh\ncargo run -- --once\ncargo run -- --interval 500ms\n```\n\nBuild and install the release binary:\n\n```sh\nmake install\nmemwatch --once\nmemwatch\n```\n\nIf `/usr/local/bin` is not in your `PATH`, either add it or install with a custom\n`PREFIX`, `BINDIR`, or `INSTALL_PATH`.\n\n## Supported Systems\n\n`memwatch` targets Linux systems that expose memory and process data through\nprocfs, SMBIOS/DMI data through sysfs or `dmidecode`, and bandwidth events\nthrough Linux perf PMUs.\n\n| System type | Support level | Notes |\n| --- | --- | --- |\n| Bare-metal Linux on Intel x86/x86_64 with uncore IMC PMUs | Full | Expected to show memory usage, DIMM details, top RSS processes, and read/write/total memory bandwidth when permissions are set up. |\n| Linux on Intel x86/x86_64 without IMC PMUs | Partial | Memory usage, DIMM details, and top RSS processes may work. Bandwidth shows `N/A` with a diagnostic. |\n| Linux on AMD x86/x86_64 | Partial | Memory usage, DIMM details, and top RSS processes may work. Bandwidth support is limited to available CPU PMU fallback events and may only report read-side activity. |\n| Linux VMs, containers, or restricted hosts | Partial | `/proc/meminfo` usually works, but DMI tables and hardware PMU counters are often hidden or blocked. |\n| Non-x86 Linux | Partial | Basic `/proc` memory and process data may work. DIMM and bandwidth data depend on platform firmware and PMU support. |\n| macOS, Windows, BSD, WSL without Linux hardware sysfs/perf access | Not supported for useful runtime data | The crate may compile on some non-Linux targets, but the monitor expects Linux `/proc`, `/sys`, and perf hardware-counter interfaces. |\n\nThe TUI requires an interactive terminal. Use `--once` for automation or\nnon-interactive environments.\n\n## Data Sources\n\n| Data | Source |\n| --- | --- |\n| System memory summary | `/proc/meminfo` |\n| Top RSS processes | `/proc/\u003cpid\u003e/status` |\n| Direct DMI/SMBIOS table | `/sys/firmware/dmi/tables/DMI` |\n| DMI fallback | `dmidecode --type memory` |\n| PMU event metadata | `/sys/bus/event_source/devices` |\n| CPU online list for AMD fallback PMU events | `/sys/devices/system/cpu/online` |\n| Memory bandwidth counters | `perf_event_open` |\n\n`memwatch` does not change memory timings, kernel tunables, process state, swap\nsettings, or any other system configuration.\n\n## Prerequisites\n\nRequired for building:\n\n- A current stable Rust toolchain.\n- Cargo.\n\nThe manifest does not currently declare a minimum supported Rust version. Use the\nrepository's `Cargo.lock` for reproducible dependency versions.\n\nOptional but recommended:\n\n- `make`, for the repository build/install targets.\n- `sudo`, `setcap`, and `getcap`, for installing the binary with Linux file\n  capabilities.\n- `dmidecode`, as a fallback when direct DMI table reads are unavailable or\n  return no installed memory-device records.\n\nOn Debian or Ubuntu-style systems, the optional runtime tools are typically in:\n\n```sh\nsudo apt install make libcap2-bin dmidecode\n```\n\nOn Fedora-style systems:\n\n```sh\nsudo dnf install make libcap dmidecode\n```\n\nDistribution package names vary. If `setcap`, `getcap`, or `dmidecode` are not\nin `PATH`, install the package that provides them for your distribution.\n\n## Building\n\nBuild a debug binary:\n\n```sh\ncargo build\n```\n\nBuild an optimized release binary:\n\n```sh\ncargo build --release\n```\n\nThe release binary is written to:\n\n```sh\ntarget/release/memwatch\n```\n\nThe Makefile wraps the release build:\n\n```sh\nmake build\n```\n\n## Building Packages\n\nBuild Debian and RPM packages:\n\n```sh\nmake package VERSION=0.1.12\nmake check-packages VERSION=0.1.12\n```\n\nPackage artifacts are written to `dist/` by default:\n\n- `memwatch_0.1.12_amd64.deb`\n- `memwatch-0.1.12-1.x86_64.rpm`\n\nBoth packages install `memwatch` to `/usr/bin/memwatch`, keep the binary\nexecutable, and run this during package installation:\n\n```sh\nsetcap cap_perfmon,cap_dac_read_search+ep /usr/bin/memwatch\n```\n\nRequired package build tools:\n\n- `dpkg-deb`, usually provided by the Debian or Ubuntu `dpkg` package.\n- `rpmbuild`, usually provided by the Fedora, RHEL, or Debian `rpm` package.\n\n## Development Checks\n\nRun the full local check suite:\n\n```sh\nmake check\n```\n\nThat runs:\n\n```sh\ncargo fmt --check\ncargo test\ncargo clippy -- -D warnings\n```\n\nYou can also run individual targets:\n\n```sh\nmake fmt\nmake test\nmake clippy\n```\n\n## Installing\n\nThe recommended install path is through the Makefile:\n\n```sh\nmake install\n```\n\nBy default this:\n\n1. Builds `target/release/memwatch` if needed.\n2. Installs it to `/usr/local/bin/memwatch`.\n3. Applies the `cap_perfmon,cap_dac_read_search+ep` file capability set.\n4. Prints the resulting capability with `getcap`.\n\nVerify the installed command:\n\n```sh\ncommand -v memwatch\nmemwatch --once\n```\n\nIf you prefer to run the privileged install step explicitly, build first and\nthen run install under `sudo`:\n\n```sh\nmake build\nsudo make install\n```\n\nThe prebuild matters because `sudo make install` runs as root and the Makefile\nexpects the release binary to already exist in that case.\n\n### Custom Install Paths\n\nInstall under a different prefix:\n\n```sh\nPREFIX=\"$HOME/.local\" make install\n```\n\nInstall to a specific binary directory:\n\n```sh\nBINDIR=\"$HOME/.local/bin\" make install\n```\n\nInstall to an exact path:\n\n```sh\nINSTALL_PATH=\"$HOME/.local/bin/memwatch\" make install\n```\n\n### Installing Without Capabilities\n\nTo install only the binary:\n\n```sh\nmake install-binary\n```\n\nWithout capabilities, `memwatch` still runs, but DMI details and memory\nbandwidth counters may be unavailable.\n\nYou can apply or reapply capabilities later:\n\n```sh\nmake capability\n```\n\nCheck the installed capabilities:\n\n```sh\nmake show-capability\ngetcap \"$(command -v memwatch)\"\n```\n\nRemove the installed binary:\n\n```sh\nmake uninstall\n```\n\n### Cargo Install\n\nYou can also install with Cargo:\n\n```sh\ncargo install --path .\n```\n\nCargo does not apply Linux file capabilities. If you need protected DMI table\nreads or perf counter access, apply the capabilities manually or use\n`make install`.\n\n## Runtime Setup\n\n### Basic Memory And Processes\n\nThe memory summary and top-RSS process list rely on `/proc`:\n\n```sh\ntest -r /proc/meminfo\nls /proc/1/status\n```\n\nThese data sources normally work as an unprivileged user on Linux. Some\ncontainers or hardened hosts may hide process details for other users.\n\n### DIMM And Speed Details\n\n`memwatch` first tries to read SMBIOS/DMI memory-device records directly from:\n\n```sh\n/sys/firmware/dmi/tables/DMI\n```\n\nIf that does not return installed memory-device records, it falls back to:\n\n```sh\ndmidecode --type memory\n```\n\nDirect DMI table reads and `dmidecode` commonly require elevated privileges or\nthe `cap_dac_read_search+ep` file capability. If DIMM details show as `N/A`, use\nthe Makefile install path or check the source manually:\n\n```sh\nsudo dmidecode --type memory\n```\n\n### Memory Bandwidth\n\nBandwidth readings use Linux perf hardware counters. `memwatch` discovers events\nunder:\n\n```sh\n/sys/bus/event_source/devices\n```\n\nOn Intel systems, full bandwidth support expects `uncore_imc_*` or\n`uncore_imc_free_running_*` event-source devices with exported read and write\nevents. Check for them with:\n\n```sh\nls /sys/bus/event_source/devices | grep uncore_imc\n```\n\nThe binary opens PMU counters with `perf_event_open`. The Makefile applies:\n\n```sh\ncap_perfmon,cap_dac_read_search+ep\n```\n\n`cap_perfmon` is the relevant capability for perf counter access on kernels that\nsupport it. Even with this capability, the kernel may still block access through\nperf policy. Check the current policy:\n\n```sh\ncat /proc/sys/kernel/perf_event_paranoid\n```\n\nIf bandwidth remains `N/A`, run a one-off diagnostic as root:\n\n```sh\nsudo target/release/memwatch --once\n```\n\nSome systems do not expose memory-controller PMU events at all. In that case the\nrest of the monitor still works and the bandwidth panel reports `N/A`.\n\n### Capabilities\n\nSome filesystems, package managers, or copy operations do not preserve Linux file\ncapabilities. If the installed binary is replaced after install, run:\n\n```sh\nmake capability\n```\n\nIf `setcap` rejects `cap_perfmon`, your kernel or libcap tooling may be too old\nfor that capability name. Basic memory reporting still works without it, but\nhardware bandwidth counters will likely remain unavailable.\n\n## Usage\n\nStart the interactive TUI:\n\n```sh\nmemwatch\n```\n\nExit the TUI with any of:\n\n- `q`\n- `Esc`\n- `Ctrl-C`\n\nUse a custom update interval:\n\n```sh\nmemwatch --interval 500ms\nmemwatch --interval 2s\n```\n\nPrint one text report and exit:\n\n```sh\nmemwatch --once\n```\n\nUse a custom sampling interval for the one-shot report:\n\n```sh\nmemwatch --once --interval 250ms\n```\n\nIn `--once` mode, `memwatch` takes an initial sample, waits for the interval,\nthen takes a second sample so bandwidth can be computed from counter deltas.\n\nShow CLI help:\n\n```sh\nmemwatch --help\n```\n\nCurrent options:\n\n```text\nUsage: memwatch [OPTIONS]\n\nOptions:\n      --interval \u003cINTERVAL\u003e  [default: 1s]\n      --once\n  -h, --help                 Print help\n```\n\n## Troubleshooting\n\n- `meminfo unavailable or unreadable`: the process cannot read `/proc/meminfo`.\n  This usually means the program is running outside Linux or inside an unusually\n  restricted environment.\n- `DMI table unreadable`: direct SMBIOS/DMI table reads failed. Install with\n  `make install`, check capabilities with `getcap \"$(command -v memwatch)\"`, or\n  verify `sudo dmidecode --type memory`.\n- `dmidecode unavailable`: install `dmidecode` if you want the fallback path for\n  DIMM details.\n- `no memory bandwidth PMU events found`: the kernel did not expose supported\n  PMU events. Basic memory and process reporting can still work.\n- `failed to open ...`: PMU events were discovered, but `perf_event_open` was\n  blocked or failed. Check capabilities and `/proc/sys/kernel/perf_event_paranoid`.\n- Bandwidth shows `N/A` on the first update: bandwidth requires two counter\n  samples. Wait for the next interval, or use `--once` with a nonzero interval.\n- Top RSS is empty: `/proc` process status files may be hidden or inaccessible in\n  the current environment.\n- The TUI does not render correctly: use a real interactive terminal with enough\n  width and height, or use `memwatch --once` for plain text output.\n\n## Repository Layout\n\n- `src/main.rs`: binary entry point.\n- `src/lib.rs`: mode selection, TUI loop, and terminal lifecycle.\n- `src/cli.rs`: command-line options.\n- `src/memory.rs`: `/proc/meminfo` parsing and memory summary calculations.\n- `src/dmi.rs`: direct SMBIOS/DMI parsing and `dmidecode` fallback parsing.\n- `src/bandwidth.rs`: PMU event discovery, perf counter setup, and bandwidth\n  calculations.\n- `src/processes.rs`: `/proc/\u003cpid\u003e/status` scanning and top-RSS sorting.\n- `src/snapshot.rs`: combined sampling state.\n- `src/render.rs`: TUI rendering and one-shot text reports.\n- `Makefile`: build, install, capability, and check targets.\n\n## Suggested GitHub Topics\n\nFor the repository About sidebar, useful topics would be:\n\n```text\nlinux\nrust\ntui\nterminal\nmemory-monitor\nram-monitor\nhardware-monitor\nperformance-monitoring\nmemory-bandwidth\nperf\npmu\ndmidecode\nratatui\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrvr-farm%2Fmemwatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrvr-farm%2Fmemwatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrvr-farm%2Fmemwatch/lists"}