{"id":17870133,"url":"https://github.com/pouriyajamshidi/qwatcher","last_synced_at":"2025-03-21T13:31:26.468Z","repository":{"id":56571925,"uuid":"522181678","full_name":"pouriyajamshidi/qwatcher","owner":"pouriyajamshidi","description":"Queue watcher helps monitor TCP connections and diagnose buffer and connectivity issues on Linux machines related to input and output queues","archived":false,"fork":false,"pushed_at":"2024-06-02T17:10:17.000Z","size":1638,"stargazers_count":23,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-18T01:43:09.644Z","etag":null,"topics":["buffer","linux","network","nim","queues","receive","send","sqlite3","tcp"],"latest_commit_sha":null,"homepage":"","language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pouriyajamshidi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2022-08-07T10:29:52.000Z","updated_at":"2024-11-20T01:47:55.000Z","dependencies_parsed_at":"2024-01-03T22:31:10.125Z","dependency_job_id":"dc94a36a-ea34-499d-a9d7-d8243496b00a","html_url":"https://github.com/pouriyajamshidi/qwatcher","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouriyajamshidi%2Fqwatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouriyajamshidi%2Fqwatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouriyajamshidi%2Fqwatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pouriyajamshidi%2Fqwatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pouriyajamshidi","download_url":"https://codeload.github.com/pouriyajamshidi/qwatcher/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244806092,"owners_count":20513378,"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":["buffer","linux","network","nim","queues","receive","send","sqlite3","tcp"],"created_at":"2024-10-28T10:12:18.757Z","updated_at":"2025-03-21T13:31:26.134Z","avatar_url":"https://github.com/pouriyajamshidi.png","language":"Nim","funding_links":["https://www.buymeacoffee.com/pouriyajamshidi","https://github.com/sponsors/pouriyajamshidi"],"categories":[],"sub_categories":[],"readme":"# Queue Watcher\n\n\u003c!-- ![qwatcher](artwork/qwatcher.png) --\u003e\n\u003c!-- \u003cimg src=\"https://github.com/pouriyajamshidi/qwatcher/blob/master/artwork/qwatcher.png?raw=true\" width=\"600\" /\u003e --\u003e\n\n\u003cdiv align=\"center\" style=\"width: 100%;\"\u003e\n \u003cimg alt=\"qwatcher\" src=\"https://github.com/pouriyajamshidi/qwatcher/blob/master/artwork/qwatcher.png?raw=true\" width=\"700\"\u003e\n\u003c/div\u003e\n\n---\n\n`qwatcher` is designed to help monitor TCP connections and diagnose **buffer** and connectivity issues on Linux machines related to `input` and `output` queues.\n\n---\n\n## Table of Contents\n\n- [Queue Watcher](#queue-watcher)\n  - [Table of Contents](#table-of-contents)\n  - [Why](#why)\n  - [How](#how)\n    - [Usage](#usage)\n    - [Available flags](#available-flags)\n  - [What](#what)\n  - [Nimble Directory](#nimble-directory)\n  - [Tested on](#tested-on)\n  - [Sponsor me](#sponsor-me)\n  - [Contact me](#contact-me)\n  - [License](#license)\n\n---\n\n## Why\n\nThe idea of writing this program came to me after reading a few blog posts discussing how they faced odd connectivity issues and how it ended up being related to the send and receive queues.\n\nHad they had this tool, they would have been able to find the root cause much faster.\n\n---\n\n## How\n\n1. Download and extract the file from this URL:\n\n   ```bash\n   wget https://github.com/pouriyajamshidi/qwatcher/releases/latest/download/qwatcher.tar.gz\n   tar xvf qwatcher.tar.gz\n   ```\n\n   Optionally, you can use `Nimble` for installation \u003chttps://nimble.directory/pkg/qwatcher\u003e and skip to step 3.\n\n   ```bash\n   nimble install qwatcher\n   ```\n\n2. Make it executable and if you prefer, move it to your `$PATH`:\n\n   ```bash\n   chmod +x qwatcher\n   sudo cp qwatcher /usr/local/bin\n   ```\n\n3. Run it. There are two modes to run `qwatcher`.\n\n   1. **Write mode**. Provides two logging methods:\n      1. Using `--db_path` to log to a database. Default path: `/var/log/qwatcher.db`\n      2. Using `--log_path` to log to a text file. Default path: `/var/log/qwatcher.log`\n   2. **Monitor mode** (default). Prints the output to the console\n\n\u003e :warning: Make sure to not feed a higher number than your current buffer size to the program.\n\nIn order to get the current read and write buffer sizes, run the following commands:\n\n```bash\ncat /proc/sys/net/ipv4/tcp_rmem\ncat /proc/sys/net/ipv4/tcp_wmem\n```\n\n---\n\n### Usage\n\nLet's explore all modes:\n\n1. check every **5 seconds** and **log** connections that surpass **100 kilobytes** in **send** or **receive** queues to a **database** located at `/var/log/qwatcher.db`:\n\n   ```bash\n   qwatcher --recv_q=100000 --send_q=100000 --refresh=5 --db_path=/var/log/qwatcher.db\n   ```\n\n   Then you can check the database. For instance, connections with `receive queue` bigger than zero:\n\n   \u003e `sqlite3` needs to be installed.\n\n   ```bash\n   # Open the database file:\n   sqlite3 /var/log/qwatcher.db\n   # Beautify sqlite output:\n   .mode line\n   .headers on\n   .separator ROW \"\\n\"\n   # Run your query:\n   sqlite\u003e SELECT * FROM qwatcher WHERE receiveQ \u003e 0;\n   ```\n\n2. Should you prefer to log the stats in a **log file** instead of a database as shown in step 1 use `--log_path`:\n\n   ```bash\n   qwatcher --recv_q=100000 --send_q=100000 --refresh=5 --log_path=/var/log/qwatcher.log\n   ```\n\n   Then you can use tail to check the file contents:\n\n   ```bash\n   tail -f /var/log/qwatcher.log\n   ```\n\n3. **Default mode**. If you want the output to be shown on the **console** and not log to disk, use the commands above without `--log_path` or `--db_path` options:\n\n   ```bash\n   qwatcher --recv_q=100000 --send_q=100000\n   ```\n\n   \u003e The default refresh interval is 10 seconds.\n\nThe sample output can be seen [here](#what)\n\nAdditionally, you can use the [accompanying systemd](qwatcher.service) service to run `qwatcher` in the background and not worry about system restarts:\n\n```bash\nsudo cp qwatcher.service /etc/systemd/system/qwatcher.service\nsudo systemctl enable qwatcher.service\nsudo systemctl start qwatcher.service\n```\n\n### Available flags\n\n```console\n  -h, --help        : show help\n  --recv_q,         : Minimum receive-Q to trigger alert in bytes (default: 10000)\n  --send_q,         : Minimum send-Q to trigger alert in bytes (default: 10000)\n  --refresh,        : Refresh interval in seconds (default: 10)\n  --db_path,        : Path to SQLite database to log reports (default: /var/log/qwatcher.db)\n  --log_path,       : Path to log file to log reports (default: /var/log/qwatcher.log)\n  -v, --version,    : Show version\n```\n\n\u003e Please note that you cannot use `--db_path` and `--log_path` at the same time.\n\n---\n\n## What\n\nBelow output depicts the provided information for a connection:\n\n![output](https://github.com/pouriyajamshidi/qwatcher/raw/master/images/qwatcher.png)\n\nApart from the send and receive queues, there are additional information that can be useful to diagnose connectivity issues such as `congestion window`, `mss`, `retransmits` and more.\n\n## Nimble Directory\n\nThis project is also hosted on [Nimble](https://nimble.directory/pkg/qwatcher).\n\n## Tested on\n\nUbuntu server 22.04.\n\n## Sponsor me\n\n[![\"Buy Me A Coffee\"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/pouriyajamshidi)  \n[![sponsor](https://img.shields.io/static/v1?label=Sponsor\u0026message=%E2%9D%A4\u0026logo=GitHub\u0026color=%23fe8e86)](https://github.com/sponsors/pouriyajamshidi)\n\n## Contact me\n\n[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white)](https://www.linkedin.com/in/pouriya-jamshidi/)\n\n## License\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpouriyajamshidi%2Fqwatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpouriyajamshidi%2Fqwatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpouriyajamshidi%2Fqwatcher/lists"}