# memsparkline
Track the RAM usage ([resident set size](https://en.wikipedia.org/wiki/Resident_set_size)) of a process, its children, its children's children, etc. in real time with a Unicode text [sparkline](https://en.wikipedia.org/wiki/Sparkline).
See the average and the maximum usage after the process exits, as well as the run time.
## Examples
```none
> memsparkline -- chromium-browser --incognito http://localhost:8081/
▁▁▁▁▄▇▇▇█ 789.5
avg: 371.0
max: 789.5
time: 0:00:12.0
```
```none
> memsparkline -n -o log du /usr/ >/dev/null 2>&1 &
> tail -f log
█ 2.8
▆█ 3.3
▆▇█ 3.6
▆▇▇█ 3.9
▆▇▇█▆ 3.3
▆▇▇█▆▆ 3.3
▆▇▇█▆▆▆ 3.3
▆▇▇█▆▆▆▆ 3.3
▄▅▅▆▅▅▅▅█ 5.2
▄▅▅▆▅▅▅▅██ 5.2
avg: 3.7
max: 5.2
time: 0:00:10.1
```
## Compatibility and limitations
memsparkline works on POSIX systems supported by [psutil](https://github.com/giampaolo/psutil).
It has been tested on Debian, Ubuntu, FreeBSD, NetBSD, and OpenBSD.
Although memsparkline seems to work on Windows, Windows support has received little testing outside of [CI](https://en.wikipedia.org/wiki/Continuous_integration).
The sparkline displays incorrectly in the Command Prompt and [ConEmu](https://conemu.github.io/) on Windows 7 with the stock console fonts.
It displays correctly on Windows 10 with the font NSimSun.
## Operation
### Usage
```none
usage: memsparkline [-h] [-v] [-d path] [-l n] [-m fmt] [-n] [-o path] [-q]
[-r ms] [-s ms] [-t fmt] [-w ms]
command ...
Track the RAM usage (resident set size) of a process and its descendants in
real time.
positional arguments:
command command to run
args arguments to command
options:
-h, --help show this help message and exit
-v, --version show program's version number and exit
-d path, --dump path file in which to write full memory usage history when
finished
-l n, --length n sparkline length (default: 20)
-m fmt, --mem-format fmt
format string for memory amounts (default: "%0.1f")
-n, --newlines print new sparkline on new line instead of over
previous
-o path, --output path
output file to append to ("-" for standard error)
-q, --quiet do not print sparklines, only final report
-r ms, --record ms how frequently to record/report memory usage (default:
every 1000 ms)
-s ms, --sample ms how frequently to sample memory usage (default: every
200 ms)
-t fmt, --time-format fmt
format string for run time (default: "%d:%02d:%04.1f")
-w ms, --wait ms set "--sample" and "--record" time simultaneously
(that both options override)
```
### Samples and records
memsparkline differentiates between _samples_ and _records_.
Samples are measurements of memory usage.
Records are information about memory usage printed to the chosen output (given by `--output`) and added to history (saved using the `--dump` option).
There is a separate setting for the sample time and the record time.
The sample time determines the interval between when memory usage is measured.
The record time determines the interval between when a record is made (written to the output and added to history).
When sampling is more frequent than recording (as with the default settings),
memsparkline uses the highest sampled value since the last record.
A short sample time like 5 ms can result in high CPU usage,
up to 100% of one CPU core.
To reduce CPU usage, sample less frequently.
The default sample time of 200 ms results in memsparkline using around 10% of a 2019 x86-64 core on the developer's machine.
Records are only created after a sample has been taken.
Setting the record time shorter than the sample time is allowed for convenience but equivalent to setting it to the sample time.
## Installation
memsparkline requires Python 3.8 or later.
### Installing from PyPI
The recommended way to install memsparkline is [from PyPI](https://pypi.org/project/memsparkline/) with [pipx](https://github.com/pypa/pipx).
```sh
pipx install memsparkline
```
You can also use pip:
```sh
pip install --user memsparkline
```
### Manual installation
1. Install the dependencies from the package repositories for your OS.
You will find instructions for some operating systems below.
2. Download `src/memsparkline/main.py` and copy it to a directory in `PATH` as `memsparkline`.
For example:
```sh
git clone https://github.com/dbohdan/memsparkline
sudo install memsparkline/src/memsparkline/main.py /usr/local/bin/memsparkline
```
#### Dependencies
##### Debian/Ubuntu
```sh
sudo apt install python3-psutil
```
##### DragonFly BSD 6.6, FreeBSD 13.1
```sh
sudo pkg install py39-psutil
```
##### NetBSD 9.3
```sh
sudo pkgin in py310-psutil
```
##### OpenBSD
```sh
doas pkg_add py3-psutil
```
## License
MIT.
## See also
memusg and spark (both linked below) inspired this project.
### Tracking memory usage
* [DragonFly BSD](https://man.dragonflybsd.org/?command=time§ion=ANY), [FreeBSD](https://man.freebsd.org/cgi/man.cgi?query=time&format=html), [NetBSD](https://man.netbsd.org/time.1), [OpenBSD](https://man.openbsd.org/time), and [macOS](https://ss64.com/osx/time.html) time(1) flag `-l`.
* [GNU time(1)](https://linux.die.net/man/1/time) flag `-v`.
* [memusg](http://gist.github.com/526585) — a Bash script for FreeBSD, Linux, and macOS that measures the peak resident set size of a process.
### Sparklines
* [spark](https://github.com/holman/spark) — a Bash script that generates a Unicode text sparkline from a list of numbers.
* [sparkline.tcl](https://wiki.tcl-lang.org/page/Sparkline) — a Tcl script by the developer of this project that does the same. Adds a `--min` and `--max` option for setting the scale.
Raw data
{
"_id": null,
"home_page": "https://github.com/dbohdan/memsparkline",
"name": "memsparkline",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "memory, monitoring, performance, RAM, resident set size, sparklines",
"author": "D. Bohdan",
"author_email": "dbohdan@dbohdan.com",
"download_url": "https://files.pythonhosted.org/packages/b9/c9/062414be58ef1e0ddac2c0846334967517c7dba074ffd289b6f0fc86fef9/memsparkline-0.6.0.tar.gz",
"platform": null,
"description": "# memsparkline\n\nTrack the RAM usage ([resident set size](https://en.wikipedia.org/wiki/Resident_set_size)) of a process, its children, its children's children, etc. in real time with a Unicode text [sparkline](https://en.wikipedia.org/wiki/Sparkline).\nSee the average and the maximum usage after the process exits, as well as the run time.\n\n\n## Examples\n\n```none\n> memsparkline -- chromium-browser --incognito http://localhost:8081/\n\u2581\u2581\u2581\u2581\u2584\u2587\u2587\u2587\u2588 789.5\n avg: 371.0\n max: 789.5\ntime: 0:00:12.0\n```\n\n```none\n> memsparkline -n -o log du /usr/ >/dev/null 2>&1 &\n> tail -f log\n\u2588 2.8\n\u2586\u2588 3.3\n\u2586\u2587\u2588 3.6\n\u2586\u2587\u2587\u2588 3.9\n\u2586\u2587\u2587\u2588\u2586 3.3\n\u2586\u2587\u2587\u2588\u2586\u2586 3.3\n\u2586\u2587\u2587\u2588\u2586\u2586\u2586 3.3\n\u2586\u2587\u2587\u2588\u2586\u2586\u2586\u2586 3.3\n\u2584\u2585\u2585\u2586\u2585\u2585\u2585\u2585\u2588 5.2\n\u2584\u2585\u2585\u2586\u2585\u2585\u2585\u2585\u2588\u2588 5.2\n avg: 3.7\n max: 5.2\ntime: 0:00:10.1\n```\n\n\n## Compatibility and limitations\n\nmemsparkline works on POSIX systems supported by [psutil](https://github.com/giampaolo/psutil).\nIt has been tested on Debian, Ubuntu, FreeBSD, NetBSD, and OpenBSD.\n\nAlthough memsparkline seems to work on Windows, Windows support has received little testing outside of [CI](https://en.wikipedia.org/wiki/Continuous_integration).\nThe sparkline displays incorrectly in the Command Prompt and [ConEmu](https://conemu.github.io/) on Windows 7 with the stock console fonts.\nIt displays correctly on Windows 10 with the font NSimSun.\n\n\n## Operation\n\n### Usage\n\n```none\nusage: memsparkline [-h] [-v] [-d path] [-l n] [-m fmt] [-n] [-o path] [-q]\n [-r ms] [-s ms] [-t fmt] [-w ms]\n command ...\n\nTrack the RAM usage (resident set size) of a process and its descendants in\nreal time.\n\npositional arguments:\n command command to run\n args arguments to command\n\noptions:\n -h, --help show this help message and exit\n -v, --version show program's version number and exit\n -d path, --dump path file in which to write full memory usage history when\n finished\n -l n, --length n sparkline length (default: 20)\n -m fmt, --mem-format fmt\n format string for memory amounts (default: \"%0.1f\")\n -n, --newlines print new sparkline on new line instead of over\n previous\n -o path, --output path\n output file to append to (\"-\" for standard error)\n -q, --quiet do not print sparklines, only final report\n -r ms, --record ms how frequently to record/report memory usage (default:\n every 1000 ms)\n -s ms, --sample ms how frequently to sample memory usage (default: every\n 200 ms)\n -t fmt, --time-format fmt\n format string for run time (default: \"%d:%02d:%04.1f\")\n -w ms, --wait ms set \"--sample\" and \"--record\" time simultaneously\n (that both options override)\n```\n\n### Samples and records\n\nmemsparkline differentiates between _samples_ and _records_.\nSamples are measurements of memory usage.\nRecords are information about memory usage printed to the chosen output (given by `--output`) and added to history (saved using the `--dump` option).\n\nThere is a separate setting for the sample time and the record time.\nThe sample time determines the interval between when memory usage is measured.\nThe record time determines the interval between when a record is made (written to the output and added to history).\nWhen sampling is more frequent than recording (as with the default settings),\nmemsparkline uses the highest sampled value since the last record.\n\nA short sample time like 5 ms can result in high CPU usage,\nup to 100% of one CPU core.\nTo reduce CPU usage, sample less frequently.\nThe default sample time of 200 ms results in memsparkline using around 10% of a 2019 x86-64 core on the developer's machine.\n\nRecords are only created after a sample has been taken.\nSetting the record time shorter than the sample time is allowed for convenience but equivalent to setting it to the sample time.\n\n\n## Installation\n\nmemsparkline requires Python 3.8 or later.\n\n### Installing from PyPI\n\nThe recommended way to install memsparkline is [from PyPI](https://pypi.org/project/memsparkline/) with [pipx](https://github.com/pypa/pipx).\n\n```sh\npipx install memsparkline\n```\n\nYou can also use pip:\n\n```sh\npip install --user memsparkline\n```\n\n### Manual installation\n\n1. Install the dependencies from the package repositories for your OS.\n You will find instructions for some operating systems below.\n2. Download `src/memsparkline/main.py` and copy it to a directory in `PATH` as `memsparkline`.\n For example:\n\n```sh\ngit clone https://github.com/dbohdan/memsparkline\nsudo install memsparkline/src/memsparkline/main.py /usr/local/bin/memsparkline\n```\n\n#### Dependencies\n\n##### Debian/Ubuntu\n\n```sh\nsudo apt install python3-psutil\n```\n\n##### DragonFly BSD 6.6, FreeBSD 13.1\n\n```sh\nsudo pkg install py39-psutil\n```\n\n##### NetBSD 9.3\n\n```sh\nsudo pkgin in py310-psutil\n```\n\n##### OpenBSD\n\n```sh\ndoas pkg_add py3-psutil\n```\n\n\n## License\n\nMIT.\n\n\n## See also\n\nmemusg and spark (both linked below) inspired this project.\n\n### Tracking memory usage\n\n* [DragonFly BSD](https://man.dragonflybsd.org/?command=time§ion=ANY), [FreeBSD](https://man.freebsd.org/cgi/man.cgi?query=time&format=html), [NetBSD](https://man.netbsd.org/time.1), [OpenBSD](https://man.openbsd.org/time), and [macOS](https://ss64.com/osx/time.html) time(1) flag `-l`.\n* [GNU time(1)](https://linux.die.net/man/1/time) flag `-v`.\n* [memusg](http://gist.github.com/526585) \u2014 a Bash script for FreeBSD, Linux, and macOS that measures the peak resident set size of a process.\n\n### Sparklines\n\n* [spark](https://github.com/holman/spark) \u2014 a Bash script that generates a Unicode text sparkline from a list of numbers.\n* [sparkline.tcl](https://wiki.tcl-lang.org/page/Sparkline) \u2014 a Tcl script by the developer of this project that does the same. Adds a `--min` and `--max` option for setting the scale.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Track the RAM usage (resident set size) of a process and its descendants in real time.",
"version": "0.6.0",
"project_urls": {
"Homepage": "https://github.com/dbohdan/memsparkline",
"Repository": "https://github.com/dbohdan/memsparkline"
},
"split_keywords": [
"memory",
" monitoring",
" performance",
" ram",
" resident set size",
" sparklines"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5a247ae0328f53e1da00ab8172a67f151d24d0417e22f42037a9da39451c07a8",
"md5": "f8ffa04e5a0b2e71b43b76f51e5524de",
"sha256": "e49325c28ceb6d62792b408431d5f2ea82e96735d18fa74a4ad38356e1f51719"
},
"downloads": -1,
"filename": "memsparkline-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f8ffa04e5a0b2e71b43b76f51e5524de",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 8949,
"upload_time": "2024-10-15T12:32:34",
"upload_time_iso_8601": "2024-10-15T12:32:34.597331Z",
"url": "https://files.pythonhosted.org/packages/5a/24/7ae0328f53e1da00ab8172a67f151d24d0417e22f42037a9da39451c07a8/memsparkline-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b9c9062414be58ef1e0ddac2c0846334967517c7dba074ffd289b6f0fc86fef9",
"md5": "b6ed4811a6bcda2298c1eae6e32b0aec",
"sha256": "57ba8f5994a8accb068f68de6d55722b760090eab1ac2cf4aa8f25563014e9f2"
},
"downloads": -1,
"filename": "memsparkline-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "b6ed4811a6bcda2298c1eae6e32b0aec",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 11653,
"upload_time": "2024-10-15T12:32:36",
"upload_time_iso_8601": "2024-10-15T12:32:36.241537Z",
"url": "https://files.pythonhosted.org/packages/b9/c9/062414be58ef1e0ddac2c0846334967517c7dba074ffd289b6f0fc86fef9/memsparkline-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-15 12:32:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dbohdan",
"github_project": "memsparkline",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "memsparkline"
}
JSON
