Metadata-Version: 2.4
Name: cqmon
Version: 1.1.0
Summary: Watch TCP connection quality for the busiest peers on this machine. IP geolocation by DB-IP (https://db-ip.com), CC-BY-4.0.
Author-email: Sam Pickles <sam@sikasecurity.com>
Keywords: network,latency,tcp,monitoring
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: src/cqmon/data/DBIP-LICENSE
Dynamic: license-file

# cq

Personal workstation tool. Not part of the Sika program.

Watch connection quality for whoever this machine is actually talking to. A Zoom call stays on screen while it is the conversation; a later Teams call takes a slot when rows reorder. No app list to maintain.

TCP RTT, jitter, and loss come from the kernel (`ss -ti`), not from probes. UDP peers (typical call audio and video) are listed only — the kernel has no per-flow UDP RTT.

Country names come from a bundled SQLite copy of the [DB-IP Lite](https://db-ip.com/) country database, licensed [CC-BY-4.0](data/DBIP-LICENSE). Attribution: IP geolocation by DB-IP (https://db-ip.com).

## Install

```bash
pip install cqmon
```

Or, from this repo, `make install` symlinks `cq` into `~/.local/bin`. The database is bundled in the package. Rebuild it with `make geo`.

PyPI project name is `cqmon` (`cq` is already another project). The command is still `cq`.

## Usage

```bash
cq                         # watch; rows keep their places for 30s
cq -n 5 -i 1               # five rows, one-second samples
cq -p 'zoom*' -p 'teams*'  # only those apps
cq -s rtt --exclude-local  # worst TCP RTT, skip LAN and loopback
cq --once --json           # one sample for scripts
cq --reorder 0             # reorder every sample
```

### Units

| Column | Unit |
| --- | --- |
| `kbps` | kilobits per second over the sample interval |
| `rtt ms` | kernel TCP round-trip time, milliseconds |
| `min ms` | kernel minimum RTT, milliseconds |
| `jit ms` | kernel RTT variance (`rttvar`), milliseconds |
| `loss %` | retransmitted outbound segments, percent of `data_segs_out` this interval |

Yes: rtt, min, and jit are milliseconds.

### Colors

Green, amber, and red apply to the `jit ms` and `loss %` columns.

| Color | Meaning |
| --- | --- |
| red | an issue in the last 30 seconds |
| amber | a minor event, the last issue was within 5 minutes, or no sample for 2–5 minutes |
| green | a clean sample within the last 2 minutes |

An issue is jitter at or above 50 ms (or half the RTT), or loss at or above 1%, or 2 or more retransmits in one sample. A smaller non-zero jitter or a single retransmit is minor. Thresholds and windows are flags.

Rows do not hop every sample. Order changes only every `--reorder` seconds (default 30). A row that still has an amber or red mark keeps its slot when there is room, so a recovered call does not vanish the moment traffic dips.

Ctrl-C stops it. Process names are shown for your own sockets. `CQ_TOP`, `CQ_INTERVAL`, and `CQ_GEO` override `-n`, `-i`, and `--geo`.

## Flags

| Flag | Meaning |
| --- | --- |
| `-n, --top N` | Rows to show. Default 8, or `CQ_TOP`. |
| `-i, --interval SECONDS` | Sample period. Default 2, minimum 0.2, or `CQ_INTERVAL`. |
| `-c, --count N` | Print N samples, then exit. Default: until interrupted. |
| `-1, --once` | Print one sample and exit. |
| `-o, --output table\|json\|csv` | Output format. Default `table`. |
| `--json`, `--csv` | Shortcuts for `-o json` and `-o csv`. |
| `-s, --sort kbps\|rtt\|minrtt\|jit\|loss\|retrans` | Sort key, applied when rows reorder. Default `kbps`. |
| `-r, --reverse` | Reverse the sort. |
| `--by peer\|flow\|process` | Group by remote IP, 4-tuple, or process. Default `peer`. |
| `--split-pid` | Do not merge sockets that only share a process name. |
| `-p, --process GLOB` | Process-name glob. Repeatable; combined with OR. |
| `--peer SPEC` | IP, substring, `:port`, `ip:port`, or CIDR. Repeatable; combined with OR. |
| `-4`, `-6` | IPv4 only, or IPv6 only. |
| `--tcp` | TCP quality only; hide UDP peers. |
| `--udp` | List established UDP peers only. |
| `--min-kbps N` | At reorder time, hide rows below this rate. |
| `--exclude-local` | Drop loopback, link-local, multicast, and private peers. |
| `--show-idle` | At reorder time, allow sockets that moved no bytes. |
| `--resolve` | Reverse-DNS peer addresses. Cached, 0.3s timeout. |
| `--batch` | Append samples instead of redrawing. Default when stdout is not a terminal. |
| `--watch` | Redraw one screen. Default for a table on a terminal. |
| `--color auto\|always\|never` | Color jit and loss. Default `auto`. `NO_COLOR` disables auto. |
| `--reorder SECONDS` | How often row order may change. Default 30. `0` reorders every sample. |
| `--red-for SECONDS` | Issues newer than this are red. Default 30. |
| `--amber-after SECONDS` | No sample for this long turns a clean row amber. Default 120. |
| `--amber-for SECONDS` | How long an issue lingers as amber. Default 300. |
| `--jit-amber MS` | RTT variance at or above this is minor. Default 15 ms. |
| `--jit-red MS` | RTT variance at or above this is an issue. Default 50 ms. |
| `--loss-red PERCENT` | Loss at or above this is an issue. Default 1. |
| `--retrans-red N` | Retransmits in one sample at or above this are an issue. Default 2. |
| `--geo PATH` | SQLite country database. Default `data/country.sqlite`, or `CQ_GEO`. |
| `--warn-rtt MS` | Also color the rtt cell amber at or above this. |
| `--warn-retrans N` | Also color loss red when this sample's retransmits are at or above this. |
| `-l, --log FILE` | Append the same text that is printed, without color or screen clears. |
| `--wide` | Also show pid, flow count, retransmits, and ports. |
| `-q, --quiet` | Omit the banner and column header. |
| `-h, --help` | Usage. |
| `--version` | Print the version. |

`--batch` and `--watch` cannot be combined. `--tcp` and `--udp` cannot be combined. `--json` and `--csv` cannot be combined.

JSON is one object per sample, with `tcp` and `udp` arrays and a `units` object. CSV has a header row, then one row per talker. `rtt_ms`, `min_rtt_ms`, and `jit_ms` are milliseconds. `loss_pct` is a percent.
