# Goodput Monitor — full public guide

Canonical URL: https://files-two-amber.vercel.app/
Release: v0.9.0 (2026-09-14)

## What Goodput is

Goodput runs a lightweight agent on each GPU node. It reads hardware capability — NVML clocks, ECC, throttle reasons, InfiniBand port state/counters, and kernel Xid events — and uploads samples every ~60 seconds to an ingest service. Samples are classified into availability weights (0.0–1.0). Infrastructure-attributable faults (IB switch flaps, Xid 79 GPU drop-offs, thermal throttling the customer cannot fix) reduce weight. Bad training code does not.

Outputs: fleet dashboard, hourly rollups, incident detection, monthly SLA reports, and exportable claim packs mapped to provider tiers.

Uptime dashboards only show whether a node was reachable. Goodput asks whether the hardware could run at spec during each interval.

## How it works

1. Install the agent on GPU nodes (one binary per node; no git clone required).
2. Samples upload every 60 seconds to ingest; a crash-safe 500MB SQLite outbox prevents loss during backend outages.
3. Open the dashboard or export an SLA claim pack with timestamped proof.

## Install — Linux (GPU servers)

Requirements:
- Docker Engine + Compose plugin
- NVIDIA driver (`nvidia-smi` must work)
- NVIDIA Container Toolkit (so Docker can see the GPU)

One-line install (copies stack to ~/goodput, pulls images, starts database + dashboard + GPU agent):

```bash
curl -fsSL https://files-two-amber.vercel.app/install-linux.sh | bash
```

Open http://localhost:8080/ — GPU data appears within ~60 seconds.

More GPU servers: run the same installer on each Linux GPU machine, or point `--endpoint` at a central ingest host.

Advanced (download script first):

```bash
curl -fsSL -O https://files-two-amber.vercel.app/install-linux.sh
chmod +x install-linux.sh && ./install-linux.sh
```

## Install — Windows (dashboard host)

Requirements:
- Docker Desktop for Windows with WSL 2 enabled
- Docker Desktop must show "Docker is running" before installing Goodput

PowerShell one-liner (installs to %USERPROFILE%\goodput):

```powershell
irm https://files-two-amber.vercel.app/install-windows.ps1 | iex
```

Open http://localhost:8080/ in Edge or Chrome.

GPU agents run on Linux, not Windows. On each GPU server run the Linux installer, or allow port 8080 through Windows Firewall so remote Linux agents can reach this host.

Mac with Docker Desktop: run the Linux install script in Terminal, or use the Windows PowerShell script flow.

## Install — iPhone & iPad (view only)

Goodput does not install on iOS. After someone runs the Linux or Windows installer:

1. Get the dashboard URL (example: http://192.168.1.50:8080/) on the same Wi-Fi or VPN.
2. Open Safari and paste the URL.
3. Optional: Share → Add to Home Screen → name it "Goodput".

Checklist: https://files-two-amber.vercel.app/guides/ios-dashboard-setup.txt

## Docker Compose (manual)

```bash
curl -fsSL -o docker-compose.yml https://files-two-amber.vercel.app/docker-compose.release.yml
docker compose up -d
```

Default dev credentials in the release compose file:
- Agent token: devtoken
- Cluster ID: local-dev
- Postgres password: devpassword

Change these before exposing the host to a network.

Docker images:
- ghcr.io/kjd07/goodput-agent:0.9.0
- ghcr.io/kjd07/goodput-ingest:0.9.0

## Kubernetes / Helm

Chart path in source repo: deploy/helm/goodput-monitor/
Agent runs as DaemonSet; ingest as a service with TimescaleDB.
Agent needs SYSLOG capability for Xid detection from /dev/kmsg.

## Agent-only deployment

You host ingest + database + dashboard. Send others the Linux install link plus your endpoint URL, bearer token, and cluster ID. They never touch your backend.

Endpoint example: http://INGEST_HOST:8080/v1/batches

## Sharing Goodput with others

Three models (same agent and data contract):

1. You host everything — run ingest, send agent install command + token + cluster ID.
2. They self-host — send this page; they download binaries or pull pre-built images (no git clone).
3. Provider with end customers — orgs and customer API keys in admin UI; each customer sees only their clusters.

## Data contract {#data-contract}

What the agent transmits. No workload data — no process names, command lines, env vars, filenames, container images, model/dataset identifiers, or memory contents.

### Transport

- POST /v1/batches — gzipped MessagePack body (wire.Batch)
- Optional Authorization: Bearer <token>
- Optional X-Goodput-Dropped-Batches — cumulative outbox eviction count

### Batch fields

| Field | Meaning |
|---|---|
| schema_version | Wire schema version |
| cluster_id | Operator-supplied cluster name |
| node_id | Node identity (default: hostname) |
| agent_version | Agent build string |
| intervals[] | Up to four 15s samples packed into one ~60s upload |

### Per-interval fields

| Field | Meaning |
|---|---|
| ts | Sample timestamp (UTC) |
| gpus[] | One entry per GPU |
| ib_ports[] | InfiniBand port counters (empty if no IB) |
| xids[] | Xid events observed since the previous interval |

### Per-GPU fields (NVML)

UUID, name, PCI bus ID, memory used/total, SM clock current/max, throttle reasons (bitmask + supported flag), temperature (°C, if supported), volatile ECC corrected/uncorrected (if supported), PCIe gen/width current/max (if supported), GPU/memory utilisation (if supported).

Fields the driver reports as unsupported are omitted or flagged — never invented as zero.

### Per-IB-port fields

Device name, port number, state, link rate (Gbps), counter deltas since the previous sample (wrap-corrected), reason codes (e.g. IB_PORT_DOWN).

### Per-Xid fields

Numeric Xid code, PCI bus ID, derived reason code (XID_<n>). Not the raw kernel-log line.

### What is never collected

Process names, PIDs, command lines, environment variables, filenames, container/image IDs, network payloads, model or dataset identifiers, tenant names, memory contents, or any customer workload identity.

## Downloads and manifest

Manifest: https://files-two-amber.vercel.app/releases/manifest.json

Artifacts (v0.9.0):
- goodput-0.9.0-linux-amd64.tar.gz

Install scripts:
- https://files-two-amber.vercel.app/install-linux.sh
- https://files-two-amber.vercel.app/install-windows.ps1

## Health checks

```bash
curl -sf http://localhost:8080/healthz && echo ok
curl -sf http://localhost:8080/v1/fleet | head
```

## Contact

kanan07linkedin@gmail.com