diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2a3d770..7ba3e3b 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -10,11 +10,13 @@ on: paths: - "docs/**" - "mkdocs.yml" + - "overrides/**" - ".github/workflows/docs.yml" pull_request: paths: - "docs/**" - "mkdocs.yml" + - "overrides/**" - ".github/workflows/docs.yml" workflow_dispatch: diff --git a/README.md b/README.md index 02e11c7..eff6689 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,18 @@ -Log the CPU and RAM a process uses — **and every process it spawns**, including -children that daemonize and detach themselves. Or follow the busiest processes -of the whole machine, as a service from boot to shutdown. +Track the CPU and RAM usage of a process — **and every process it spawns**, +including children that daemonize and detach themselves. Or follow the busiest +processes of the whole machine, as a service from boot to shutdown. + +treehawk is a free, open-source resource usage monitor for Linux and macOS: + +- **Track CPU usage** and **track RAM usage** of any command, script or running + process, including its child processes. +- **Log resource usage over time** and get peak and average memory and CPU. +- **Find memory leaks** and CPU spikes across the whole machine. +- **Get a PDF report** with charts of CPU and memory usage. +- Tracking GPU usage is planned. **Documentation: ** diff --git a/docs/development.md b/docs/development.md index 6f57240..150291d 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,3 +1,13 @@ +--- +title: Develop treehawk +description: >- + Build, test and extend treehawk, the open-source Python process CPU and memory monitor: checks, project layout, and where to add metrics like GPU. +keywords: + - python process monitor + - open source resource monitor + - track gpu usage +--- + # Development ```bash diff --git a/docs/how-it-works.md b/docs/how-it-works.md index 0ce875f..4680c03 100644 --- a/docs/how-it-works.md +++ b/docs/how-it-works.md @@ -1,3 +1,14 @@ +--- +title: How treehawk tracks process CPU and memory +description: >- + How treehawk finds every process in a workload, even daemons that detach, and measures CPU and memory with RSS, PSS and cgroups. Limits included. +keywords: + - monitor detached processes + - process memory rss pss + - cgroup memory usage + - monitor child processes +--- + # How it works The first four sections cover `watch` and `run`; [Whole-machine @@ -121,4 +132,5 @@ named again only after growing another 25%. treehawk keeps on screen and for the summary is capped. - A spike needs 15 s of history for that process, and a leak suspect needs 30 minutes of steady growth. -- GPU usage is not collected yet. The `top` log already has a column for it. +- Tracking GPU usage is planned but not collected yet. The `top` log already + has a column for it. diff --git a/docs/index.md b/docs/index.md index fc42550..d86b4ca 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,14 +1,25 @@ --- -title: Introduction +title: Track CPU and RAM usage of a process and its children +description: >- + treehawk tracks CPU and RAM usage of a process and every child it spawns, even detached daemons. Free resource usage monitor for Linux and macOS. +keywords: + - track cpu usage + - track ram usage + - track memory usage + - track resource usage + - monitor process cpu and memory + - monitor child processes + - log cpu usage over time + - python process monitor ---
- +treehawk logo

treehawk

-Log the CPU and RAM a process uses, and every process it spawns, +Track the CPU and RAM usage of a process and every process it spawns, **including children that daemonize and detach themselves**. [Get started](#quick-tour){ .md-button .md-button--primary } @@ -16,7 +27,8 @@ Log the CPU and RAM a process uses, and every process it spawns,
-Point treehawk at something already running, or let it start the command. It +treehawk is a free, open-source resource usage monitor for the command line. +Point it at something already running, or let it start the command. It samples until the workload ends, then leaves a log you can summarise in the terminal or turn into a PDF report. It can also follow the busiest processes of the whole machine, as a service from boot to shutdown. @@ -25,7 +37,7 @@ It runs on Linux and macOS, including Apple Silicon, and reads the kernel directly. The two platforms differ in what the kernel will total up for you: see [Platforms](platforms.md). -![The treehawk live dashboard](assets/output/dashboard.svg) +![The treehawk live dashboard tracking CPU and memory usage](assets/output/dashboard.svg) ## Why diff --git a/docs/install.md b/docs/install.md index 843eb63..761bc49 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,7 +1,18 @@ +--- +title: Install treehawk on Linux and macOS +description: >- + Install treehawk, the CPU and memory usage monitor, on Linux and macOS (including Apple Silicon) with one command. Upgrade and uninstall steps too. +keywords: + - install cpu monitor linux + - install memory monitor macos + - track cpu usage + - track ram usage +--- + # Install -treehawk runs on Linux and macOS, including Apple Silicon, with Python 3.10 or -newer. +treehawk, the CPU and RAM usage tracker, runs on Linux and macOS, including +Apple Silicon, with Python 3.10 or newer. ```bash curl -LsSf https://github.com/ibadrather/treehawk/releases/latest/download/install.sh | sh diff --git a/docs/machine.md b/docs/machine.md index c31c084..92d53f9 100644 --- a/docs/machine.md +++ b/docs/machine.md @@ -1,7 +1,20 @@ +--- +title: Monitor top processes and memory leaks +description: >- + Monitor the top processes by CPU and memory on the whole machine, catch CPU spikes and find memory leaks. Runs as a systemd service from boot. +keywords: + - monitor top processes + - find memory leaks + - track resource usage + - systemd resource monitoring + - top processes logger + - cpu spike detection +--- + # Track the whole machine -`treehawk top` looks at **every** process on the machine and logs the top N by -CPU and the top N by memory. It runs until it is stopped. It also logs two kinds +`treehawk top` monitors **every** process on the machine and logs the top N by +CPU and the top N by memory (RAM). It runs until it is stopped. It also logs two kinds of trouble for any process, whether or not it ranks: - **spike**: a reading far above that process' own recent baseline, such as diff --git a/docs/platforms.md b/docs/platforms.md index 77420a0..c54ca04 100644 --- a/docs/platforms.md +++ b/docs/platforms.md @@ -1,5 +1,12 @@ --- -title: Platforms +title: Monitor CPU and memory on Linux and macOS +description: >- + How treehawk tracks CPU and memory usage on Linux (procfs, cgroups) and macOS including Apple Silicon (libproc), and what differs between them. +keywords: + - monitor cpu usage macos + - process memory monitor linux + - apple silicon cpu monitor + - cgroup memory usage --- # Platforms diff --git a/docs/results.md b/docs/results.md index bed6193..75686da 100644 --- a/docs/results.md +++ b/docs/results.md @@ -1,7 +1,19 @@ +--- +title: CPU and memory usage report in the terminal or PDF +description: >- + Turn a treehawk log into a CPU and memory usage report: a terminal summary, JSON, or a PDF with charts of CPU and RAM usage over time. +keywords: + - cpu usage report pdf + - memory usage report + - log cpu usage over time + - peak memory usage + - resource usage charts +--- + # Read the results -Every run leaves a log. `report` summarises it in the terminal, and `pdf` turns -it into a report. Both work on either kind of log (a `watch`/`run` log or a +Every run leaves a log of CPU and memory usage over time. `report` summarises it +in the terminal, and `pdf` turns it into a report with charts. Both work on either kind of log (a `watch`/`run` log or a `top` directory) and tell them apart by the log's header. They also work on the log of an interrupted run, because the summary is recomputed from the samples that were written. @@ -52,9 +64,9 @@ A workload log becomes eight pages, each answering one question. Pages that need per-process detail are left out of an `--aggregate-only` log rather than printed blank. -![Overview page](assets/output/pdf-page-1.png) +![Overview page of the CPU and memory usage PDF report](assets/output/pdf-page-1.png) -![CPU over time page](assets/output/pdf-page-2.png) +![CPU usage over time page](assets/output/pdf-page-2.png) ![Process lifetimes page](assets/output/pdf-page-4.png) diff --git a/docs/workload.md b/docs/workload.md index d78b5ac..f1917f7 100644 --- a/docs/workload.md +++ b/docs/workload.md @@ -1,7 +1,20 @@ +--- +title: Track CPU and memory usage of a command +description: >- + Track CPU and RAM usage of a command or a running process, including every child process it spawns. Log resource usage over time until it exits. +keywords: + - track cpu usage of a process + - track memory usage of a command + - monitor child processes + - monitor detached processes + - ml training resource usage + - peak memory usage +--- + # Track a workload -`watch` and `run` follow one workload, meaning a process and everything it -spawns, and write a log you read back with [`report` and `pdf`](results.md). +`watch` and `run` track the CPU and memory usage of one workload, meaning a +process and everything it spawns, and write a log you read back with [`report` and `pdf`](results.md). Both sample until the workload ends. `Ctrl-C` or a `SIGTERM` stops them early, and the log still ends with a complete summary. diff --git a/mkdocs.yml b/mkdocs.yml index 66258cd..d10842f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,9 @@ site_name: treehawk -site_description: Log the CPU and RAM of a process and every process it spawns, including ones that detach. +site_description: >- + Track CPU and RAM usage of a process and every process it spawns, even + detached daemons. A free command-line resource usage monitor for Linux and + macOS, with a live dashboard, logs and PDF reports. +site_author: Ibad Rather site_url: https://ibadrather.github.io/treehawk/ repo_url: https://github.com/ibadrather/treehawk repo_name: ibadrather/treehawk @@ -7,6 +11,7 @@ edit_uri: edit/main/docs/ theme: name: material + custom_dir: overrides logo: assets/brand/logo.svg favicon: assets/brand/logo.svg font: false # brand fonts are loaded by stylesheets/extra.css @@ -29,6 +34,27 @@ theme: icon: material/brightness-4 name: Switch to light mode +extra: + author: Ibad Rather + # Paste the codes from Google Search Console / Bing Webmaster Tools here. + google_site_verification: "" + bing_site_verification: "" + social_image: assets/output/pdf-page-1.png + social_image_alt: A treehawk PDF report of CPU and memory usage over time + keywords: + - track cpu usage + - track ram usage + - track memory usage + - track resource usage + - monitor process cpu and memory + - log cpu usage over time + - monitor child processes + - process memory monitor linux + - monitor cpu usage macos + - find memory leaks + - peak memory usage + - python process monitor + extra_css: - stylesheets/extra.css diff --git a/overrides/main.html b/overrides/main.html new file mode 100644 index 0000000..bdbfee1 --- /dev/null +++ b/overrides/main.html @@ -0,0 +1,55 @@ +{% extends "base.html" %} + +{#- Search and social metadata. The title and description come from each + page's front matter, falling back to the site's; keywords likewise. -#} +{% block extrahead %} + {%- set seo_title = (page.meta.title ~ " - " ~ config.site_name) if page.meta and page.meta.title else config.site_name -%} + {%- set seo_description = page.meta.description if page.meta and page.meta.description else config.site_description -%} + {%- set seo_keywords = page.meta.keywords if page.meta and page.meta.keywords else config.extra.keywords -%} + {%- set seo_image = config.site_url ~ config.extra.social_image -%} + {%- if seo_keywords %} + + {%- endif %} + {%- if config.extra.google_site_verification %} + + {%- endif %} + {%- if config.extra.bing_site_verification %} + + {%- endif %} + + + + + + + + + + + + + {%- if page.is_homepage %} + + {%- endif %} +{% endblock %} diff --git a/pyproject.toml b/pyproject.toml index bb819fa..6bb74dc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,13 +1,34 @@ [project] name = "treehawk" -version = "0.8.0" -description = "Log CPU and RAM usage of a process and every process it spawns, detached or not." +version = "0.8.1" +description = "Track CPU and RAM usage of a process and every process it spawns, detached or not. A resource usage monitor for Linux and macOS." readme = "README.md" license = "MIT" license-files = ["LICENSE"] authors = [{ name = "Ibad Rather", email = "ibad.rather.ir@gmail.com" }] requires-python = ">=3.10" -keywords = ["monitoring", "cpu", "memory", "process", "cgroup", "procfs", "macos", "libproc"] +keywords = [ + "cpu-usage", + "memory-usage", + "ram-usage", + "resource-usage", + "resource-monitor", + "process-monitor", + "system-monitor", + "cpu-monitor", + "memory-monitor", + "memory-leak", + "monitoring", + "cpu", + "memory", + "ram", + "process", + "linux", + "macos", + "cgroup", + "procfs", + "libproc", +] classifiers = [ "Development Status :: 3 - Alpha", "Environment :: Console", @@ -33,7 +54,8 @@ dependencies = [ ] [project.urls] -Homepage = "https://github.com/ibadrather/treehawk" +Homepage = "https://ibadrather.github.io/treehawk/" +Documentation = "https://ibadrather.github.io/treehawk/" Repository = "https://github.com/ibadrather/treehawk" Issues = "https://github.com/ibadrather/treehawk/issues" Releases = "https://github.com/ibadrather/treehawk/releases" diff --git a/uv.lock b/uv.lock index ef6029a..d32389b 100644 --- a/uv.lock +++ b/uv.lock @@ -1199,7 +1199,7 @@ wheels = [ [[package]] name = "treehawk" -version = "0.8.0" +version = "0.8.1" source = { editable = "." } dependencies = [ { name = "matplotlib", version = "3.10.9", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },