pixel/pulsewise-collector
1
0
Fork 0
mirror of https://github.com/wearepixel/pulsewise-collector.git synced 2026-11-14 22:12:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README with correct install URL, 60s interval, and full capability list

Browse Source
This commit is contained in:
Joel Male
2026-02-26 16:19:36 +10:00
parent 4018ba5c4a
commit 3cb7bc7d60
1 changed files with 73 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+73 -35
View File
@@ -1,40 +1,55 @@
# Pulsewise Collector # 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 ## Quick Install
```bash ```bash
curl -sSL https://pulsewise.app/install-collector.sh | TOKEN=your-token sudo -E bash curl -sSL https://pulsewise.app/collector/install.sh | TOKEN=<your-token> sudo -E bash
``` ```
That's it. The script downloads the binary, writes the config, and starts a systemd service. Hostname is auto-detected. 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.
If you prefer an interactive install (prompts for token and hostname):
```bash
curl -sSL https://pulsewise.app/install-collector.sh | sudo bash
```
## What It Collects ## What It Collects
Every 30 seconds, the collector sends: Every 60 seconds, the collector sends:
| Category | Metrics | | 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 | | **Uptime** | Seconds since boot |
| **Load average** | 1m, 5m, 15m | | **Load average** | 1m, 5m, 15m |
| **CPU** | Overall %, per-core %, core count | | **CPU** | Overall %, per-core %, iowait %, core count |
| **Memory** | Total, available, used, usage % | | **Memory** | Total, available, used, usage % |
| **Swap** | Total, used, free, usage % | | **Swap** | Total, used, free, usage % |
| **Disks** | Per mount point: device, fstype, total, free, used, usage % | | **Disks** | Per physical mount: device, fstype, total, free, used, usage % (virtual/loop mounts excluded) |
| **Disk I/O** | Read/write bytes, read/write count, IOPS in progress | | **Disk I/O** | Cumulative read/write bytes, read/write count, IOPS in progress |
| **Network** | Bytes and packets sent/received per second (rate, not cumulative) | | **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 | | **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. 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 ## Configuration
Config lives at `/etc/pulsewise-collector/config`: Config lives at `/etc/pulsewise-collector/config`:
@@ -50,12 +65,51 @@ ## Configuration
| `TOKEN` | *(required)* | Your Pulsewise API token | | `TOKEN` | *(required)* | Your Pulsewise API token |
| `HOSTNAME` | System hostname | Override the reported hostname | | `HOSTNAME` | System hostname | Override the reported hostname |
| `URL` | `https://pulsewise.app/api/collect` | Override the API endpoint | | `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). Config file permissions should be `600` (root-only readable).
For local development on macOS, the collector also checks `~/.config/pulsewise-collector/config`. 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 <token>`
- 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 ## Development
```bash ```bash
@@ -79,27 +133,11 @@ # Build and run
## Cross-Compiling ## Cross-Compiling
```bash ```bash
GOOS=linux GOARCH=amd64 go build -o pulsewise-collector-linux-amd64 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=arm64 go build -o pulsewise-collector-linux-arm64 .
``` ```
Or use `./deploy.sh` to compile both architectures and copy them into the Pulsewise Laravel app. Or run `./deploy.sh` to bump the version, compile all targets, and publish a release.
## 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 <token>`
- 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
## License ## License