{"id":15908868,"url":"https://github.com/dnouri/sillywalks","last_synced_at":"2026-02-09T04:37:47.030Z","repository":{"id":255913077,"uuid":"850820619","full_name":"dnouri/sillywalks","owner":"dnouri","description":"sillywalks 🎩👞: a CLI resource monitor","archived":false,"fork":false,"pushed_at":"2024-09-11T18:32:56.000Z","size":102,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-18T07:43:15.628Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/dnouri.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}},"created_at":"2024-09-01T21:40:43.000Z","updated_at":"2024-09-11T18:32:57.000Z","dependencies_parsed_at":"2024-09-07T20:36:17.643Z","dependency_job_id":"4111019d-2594-4b30-80d6-c2f53786b1f4","html_url":"https://github.com/dnouri/sillywalks","commit_stats":null,"previous_names":["dnouri/sillywalks"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2Fsillywalks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2Fsillywalks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2Fsillywalks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnouri%2Fsillywalks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnouri","download_url":"https://codeload.github.com/dnouri/sillywalks/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244902929,"owners_count":20529114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-10-06T14:40:50.283Z","updated_at":"2026-02-09T04:37:46.979Z","avatar_url":"https://github.com/dnouri.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sillywalks 🎩👞\n\n## 🦜 About\n\nsillywalks is a command-line tool for monitoring CPU, memory, and I/O\nusage of a process and its subprocesses. It provides real-time\nstatistics and generates time-series plots, offering insights into\nresource consumption over time.\n\nHere's a YouTube video that shows usage:\n\n[![sillywalks intro](https://img.youtube.com/vi/3a7gU9Y_5f4/0.jpg)](https://www.youtube.com/watch?v=3a7gU9Y_5f4)\n\n## 🧀 Features\n\n- Tracks CPU usage, memory consumption, and I/O rates\n- Monitors the main process and its subprocesses\n- Provides real-time console updates\n- Generates time-series plots for easy visualization\n- Offers optional Prometheus metrics output\n\n## 🛋️  Installation\n\nIt's recommended to use a virtual environment:\n\n```bash\npython3 -m venv venv\nsource venv/bin/activate\npip install -U pip wheel\n```\n\nInstall sillywalks from source:\n\n```bash\npip install -e \".[devel]\"\n```\n\nOr from PyPI (soon):\n\n```bash\npip install sillywalks\n```\n\n## 🥥 Usage\n\nRun sillywalks from the command line:\n\n```bash\nsillywalks [options] \u003ccommand\u003e [args...]\n```\n\nReplace `\u003ccommand\u003e` with the program you want to monitor, and\n`[args...]` with any arguments for that program.\n\n### 🎛️ Options\n\n- `--frequency FLOAT`: Set the logging frequency in Hz (default: 10.0)\n- `--no-console`: Disable console output\n- `--prometheus`: Enable Prometheus metrics\n- `--port INT`: Set the port for Prometheus metrics server (default: 8000)\n\n### 📚 Examples\n\n1. Monitor a Python script:\n   ```bash\n   sillywalks python3 my_script.py\n   ```\n\n2. Watch a video encoding process:\n   ```bash\n   sillywalks ffmpeg -i input.mp4 -c:v libx264 -crf 23 output.mp4\n   ```\n\n3. Track a machine learning training job and enable the Prometheus metrics:\n   ```bash\n   sillywalks --prometheus python3 train_model.py --epochs 100 --batch-size 32\n   ```\n\n## 📊 Output\n\nsillywalks provides two types of output:\n\n1. Real-time console updates: These appear in your terminal as the\n   monitored process runs.\n2. Time-series plot: A PNG file showing how resource usage changes\n   over time.\n\nThe plot includes separate graphs for memory usage, CPU usage, and I/O\nrates (read and write).\n\n## 🔧 Under the Hood\n\nsillywalks uses [psutil](https://psutil.readthedocs.io/) (Python\nSystem and Process Utilities) to collect resource usage data. It\nperiodically samples the process and its subprocesses, calculating CPU\nusage, memory consumption, and I/O rates. The tool uses\n[matplotlib](https://matplotlib.org/) to generate the time-series\nplots.\n\nKey points:\n\n- CPU usage is calculated as a percentage of total CPU time.\n- Memory usage is measured in megabytes (MB) using the Unique Set Size (USS).\n- I/O rates are calculated in megabytes per second (MB/s) for both\n  read and write operations.\n\n## 📊 Prometheus Integration\n\nsillywalks offers integration with\n[Prometheus](https://prometheus.io/), a powerful monitoring and\nalerting toolkit. This feature allows you to collect and store metrics\nover time, enabling advanced querying, visualization, and alerting\ncapabilities.\n\n### Activating Prometheus Output\n\nTo enable Prometheus metrics, use the `--prometheus` flag:\n\n```bash\nsillywalks --prometheus your_command\n```\n\nBy default, the Prometheus metrics server starts on port 8000. Specify\na different port with `--port`:\n\n```bash\nsillywalks --prometheus --port 9090 your_command\n```\n\n### Available Metrics\n\nsillywalks exposes the following metrics:\n\n- `process_memory_usage_mb`: Memory usage in MB\n- `process_cpu_usage_percent`: CPU usage in percent\n- `process_io_read_mbps`: I/O read rate in MB/s\n- `process_io_write_mbps`: I/O write rate in MB/s\n\n### Using Prometheus with sillywalks\n\n1. Configure Prometheus to scrape metrics from the sillywalks\n   endpoint. Refer to the [Prometheus configuration\n   documentation](https://prometheus.io/docs/prometheus/latest/configuration/configuration/)\n   for details.\n\n2. Use PromQL to query and analyze your data. Check the [PromQL\n   documentation](https://prometheus.io/docs/prometheus/latest/querying/basics/)\n   for query examples and best practices.\n\n3. Visualize metrics using [Grafana](https://grafana.com/) or the\n   Prometheus web UI. The [Grafana\n   documentation](https://grafana.com/docs/grafana/latest/getting-started/get-started-grafana-prometheus/)\n   provides guidance on setting up dashboards.\n\n4. Set up alerts based on your metrics. The [Prometheus alerting\n   documentation](https://prometheus.io/docs/alerting/latest/overview/)\n   explains how to configure alerting rules.\n\nBy integrating sillywalks with Prometheus, you can gain deeper\ninsights into your process's behavior over time and incorporate this\nmonitoring into your broader observability infrastructure.\n\n## 🤔 When to Use sillywalks\n\nsillywalks is ideal for high-level resource monitoring of\nprocesses. Use it when you want to:\n\n- Understand the overall resource consumption of a program\n- Identify performance bottlenecks at a process level\n- Monitor long-running tasks or background processes\n\nFor more detailed, code-level insights, consider using a profiler like\n[py-spy](https://github.com/benfred/py-spy) in conjunction with\nsillywalks.\n\n## 🧹 Linting\n\nWe use Ruff and Black to lint and prettify the code.  You may want to\ninstall the respective plug-ins for your editor.  To run Black and\nRuff in your source checkout, use:\n\n```bash\nmake lint\n```\n\n## 🐟 References\n\n- Daniel [blogged about how I used an LLM to write the code for\n  sillywalks](https://danielnouri.org/notes/2024/09/02/the-hottest-new-programming-language-is-english/).\n  The blog post contains lessons learned and advice on how to best\n  learn the skill of [prompt\n  engineering](https://huggingface.co/docs/transformers/en/tasks/prompting)\n  for beginners and others!\n\n- This software uses [psutil](https://psutil.readthedocs.io/) at its\n  core.  psutil is a cross-platform library for retrieving information\n  on running processes and system utilization (CPU, memory, disks,\n  network, sensors) in Python.\n\n- Monty Python's [Ministry of Silly Walks on\n  YouTube](https://youtu.be/iV2ViNJFZC8)\n\n## 🐮 Contributing\n\nContributions are welcome! Feel free to submit issues or pull requests\non our GitHub repository. Whether you're fixing bugs, adding features,\nor improving documentation, your help is appreciated.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnouri%2Fsillywalks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnouri%2Fsillywalks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnouri%2Fsillywalks/lists"}