From 3cb7bc7d60eed74fa565054a9a1e8ce94aacc096 Mon Sep 17 00:00:00 2001 From: Joel Male Date: Thu, 26 Feb 2026 16:19:36 +1000 Subject: [PATCH] docs: update README with correct install URL, 60s interval, and full capability list --- README.md | 108 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 73 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 20f3d91..7e470ac 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,55 @@ # Pulsewise Collector -Lightweight system metrics collector that reports CPU, memory, disk, network, and process data to [Pulsewise](https://pulsewise.app). +Lightweight system metrics collector that reports to [Pulsewise](https://pulsewise.app). ## Quick Install ```bash -curl -sSL https://pulsewise.app/install-collector.sh | TOKEN=your-token sudo -E bash +curl -sSL https://pulsewise.app/collector/install.sh | TOKEN= sudo -E bash ``` -That's it. The script downloads the binary, writes the config, and starts a systemd service. Hostname is auto-detected. - -If you prefer an interactive install (prompts for token and hostname): - -```bash -curl -sSL https://pulsewise.app/install-collector.sh | sudo bash -``` +The script downloads the binary, writes the config, registers the service, and starts it. Hostname is auto-detected from the system. If you omit the `TOKEN=` prefix, the script will prompt for it interactively. ## What It Collects -Every 30 seconds, the collector sends: +Every 60 seconds, the collector sends: | Category | Metrics | |----------|---------| -| **System** | OS, platform, platform version, kernel version, architecture, virtualization type, CPU model | +| **System** | OS, platform, platform version, kernel, architecture, virtualization type, CPU model | | **Uptime** | Seconds since boot | | **Load average** | 1m, 5m, 15m | -| **CPU** | Overall %, per-core %, core count | +| **CPU** | Overall %, per-core %, iowait %, core count | | **Memory** | Total, available, used, usage % | | **Swap** | Total, used, free, usage % | -| **Disks** | Per mount point: device, fstype, total, free, used, usage % | -| **Disk I/O** | Read/write bytes, read/write count, IOPS in progress | -| **Network** | Bytes and packets sent/received per second (rate, not cumulative) | +| **Disks** | Per physical mount: device, fstype, total, free, used, usage % (virtual/loop mounts excluded) | +| **Disk I/O** | Cumulative read/write bytes, read/write count, IOPS in progress | +| **Network** | Bytes and packets sent/received per second (per-second rate, not cumulative) | +| **TCP** | Established, TIME_WAIT, CLOSE_WAIT, and LISTEN connection counts | +| **File descriptors** | Open fd count and system maximum | | **Processes** | Top 10 by CPU: PID, name, command, CPU%, memory%, CPU time, RSS | +Optional integrations (configured separately): + +| Category | Metrics | +|----------|---------| +| **PHP-FPM** | Active/idle/total workers, max children reached, slow requests, listen queue, accepted connections | +| **Nginx** | Active connections, reading/writing/waiting, accepts/handled/requests | +| **SSL certificates** | Days until expiry, expiry date, validity status per domain | +| **Port checks** | TCP reachability per port with service name (ssh, mysql, redis, etc.) | + See [`payload.json`](payload.json) for a full example of the JSON sent to the API. +## CLI Commands + +```bash +sudo pulsewise-collector version # show version, check for updates +sudo pulsewise-collector update # download and install latest version +sudo pulsewise-collector status # show config, service state, last pulse +sudo pulsewise-collector dump # print full metrics payload as JSON +sudo pulsewise-collector uninstall # remove binary, config, and service +``` + ## Configuration Config lives at `/etc/pulsewise-collector/config`: @@ -50,12 +65,51 @@ ## Configuration | `TOKEN` | *(required)* | Your Pulsewise API token | | `HOSTNAME` | System hostname | Override the reported hostname | | `URL` | `https://pulsewise.app/api/collect` | Override the API endpoint | -| `DEBUG` | `false` | Log full response body from the server | +| `AUTO_UPDATE` | `true` | Set to `false` to disable automatic updates | +| `DEBUG` | `false` | Log full API response body | + +### Optional integrations + +| Key | Example | Description | +|-----|---------|-------------| +| `FPM_STATUS_URL` | `http://127.0.0.1/fpm-status` | PHP-FPM status page URL (`pm.status_path` must be set in your pool config) | +| `NGINX_STATUS_URL` | `http://127.0.0.1/nginx-status` | Nginx `stub_status` URL | +| `SSL_DOMAINS` | `example.com,api.example.com` | Comma-separated domains to check SSL cert expiry on | +| `CHECK_PORTS` | `22,80,443,3306,6379` | Comma-separated ports to check TCP availability on | + +See [`config.example`](config.example) for a commented reference. Config file permissions should be `600` (root-only readable). For local development on macOS, the collector also checks `~/.config/pulsewise-collector/config`. +## Managing the Service + +**Linux (systemd)** +```bash +sudo systemctl status pulsewise-collector +sudo journalctl -u pulsewise-collector -f +sudo systemctl restart pulsewise-collector +sudo systemctl stop pulsewise-collector +``` + +**macOS (launchd)** +```bash +tail -f /var/log/pulsewise-collector.log +sudo launchctl kickstart -k system/app.pulsewise.collector +sudo launchctl bootout system /Library/LaunchDaemons/app.pulsewise.collector.plist +``` + +## How It Works + +- Collects metrics every **60 seconds** using [gopsutil](https://github.com/shirou/gopsutil) +- CPU and process metrics are sampled concurrently over the same 1-second window to keep them aligned +- Virtual/pseudo filesystems (tmpfs, squashfs, loop devices, etc.) are excluded from disk metrics +- Network metrics are per-second rates computed from the delta between collections; the first collection omits network +- Sends JSON via `POST` to the configured URL with `Authorization: Bearer ` +- Checks for updates at startup (after 30s) and every 6 hours; updates are applied via service restart +- Runs as a systemd (Linux) or launchd (macOS) service with automatic restart on failure + ## Development ```bash @@ -79,27 +133,11 @@ # Build and run ## Cross-Compiling ```bash -GOOS=linux GOARCH=amd64 go build -o pulsewise-collector-linux-amd64 -GOOS=linux GOARCH=arm64 go build -o pulsewise-collector-linux-arm64 +GOOS=linux GOARCH=amd64 go build -o pulsewise-collector-linux-amd64 . +GOOS=linux GOARCH=arm64 go build -o pulsewise-collector-linux-arm64 . ``` -Or use `./deploy.sh` to compile both architectures and copy them into the Pulsewise Laravel app. - -## Managing the Service - -```bash -sudo systemctl status pulsewise-collector -sudo journalctl -u pulsewise-collector -f -sudo systemctl restart pulsewise-collector -sudo systemctl stop pulsewise-collector -``` - -## How It Works - -- Collects metrics every 30 seconds using [gopsutil](https://github.com/shirou/gopsutil) -- Sends JSON via `POST` to the configured URL with `Authorization: Bearer ` -- Network metrics are computed as per-second rates (delta between intervals); the first collection sends `null` for network -- Runs as a systemd service with automatic restart on failure +Or run `./deploy.sh` to bump the version, compile all targets, and publish a release. ## License