# os

The os plugin reports the host itself. It sends CPU counters, memory, real disks, load average, uptime, network throughput, IPv4 addresses and a short list of known service processes. Turn it on for every machine you run an agent on. It is the plugin that fills in the host's OS details and last-seen time on the system record.

## Enable it

Add `os` to the `plugins` array.

```json
{
  "plugins": ["os"],
  "os": {
    "refreshInterval": 30000
  }
}
```

| Option | Default | What it does |
|---|---|---|
| `refreshInterval` | `30000` | Milliseconds between reports. The plugin sends one report at startup, then one per interval. |

The plugin always reports under the unique id `os` and names the service after the machine's hostname. A `name` or `uniqueId` in this section has no effect.

## What it reports

One payload per interval.

- `hostname`, `platform`, `type`, `release`, `arch`.
- `cpus` is the raw `os.cpus()` array, with per-core `times`.
- `totalmem` and `freemem` in bytes. `available` is the memory the kernel can hand out without swapping. On Linux it comes from `MemAvailable` in `/proc/meminfo`. On macOS it is free + inactive + speculative + purgeable pages from `vm_stat`. Elsewhere it falls back to `freemem`.
- `disks` lists real drives from `df`, sorted fullest first. Each entry has `device`, `fstype`, `mount`, `total`, `used`, `free` and `pct`. The plugin drops pseudo filesystems such as tmpfs, overlay and squashfs, loop devices, and bind-mount duplicates. On macOS it keeps `/` and `/Volumes/*`, and reports the Data volume as `/`.
- `network` has `rxBytes`, `txBytes`, `rxRate` and `txRate` in bytes per second. The plugin skips loopback and virtual interfaces such as `veth*`, `docker*`, `br-*` and `tun*`. The first report has no `network` field, because a rate needs two samples.
- `processes` aggregates nginx, php-fpm, mysql/mariadb, postgres, redis and node processes from `ps`. Each entry has `name`, `count`, `cpu` and `mem` in bytes. The `cpu` figure is `ps` %cpu, which is an average over each process's lifetime.
- `loadavg`, `uptime` in seconds, and `addresses`, the first non-internal IPv4 address per interface.

## When it alerts

The server's `os` case checks `cpu > 90` and `memory.usedPercent > 90` and would raise a warning for either. The plugin sends neither field, so in practice the os plugin never raises an alert.

Every os report still updates the system record. It writes `os` (platform, release, arch), `ip_address`, `last_seen` and `status`.

## On the dashboard

The card is a bar card titled with the hostname, labelled `OS · <platform>`.

| Reading | How it is computed | Warn | Crit |
|---|---|---|---|
| CPU bar | `1 - idle / total` summed over `cpus[].times` | above 70% | above 85% |
| Memory bar | `(totalmem - available) / totalmem` | above 78% | above 85% |
| DISK | fullest entry in `disks` | 80% or more | 90% or more |
| LOAD | 5-minute load average divided by core count | 1.0 per core | 2.0 per core |
| NET | `rxRate + txRate` | none | none |
| UPTIME | `uptime` in hours | none | none |

CPU, memory and disk pressure raise the card's color and status word. That is display only. It does not change the stored status and does not send a notification.

A host that has not reported for 300 seconds shows `OFFLINE` with the time since its last report.

## Requirements

- `ps` and `df` on the PATH.
- Linux reads `/proc/meminfo` and `/proc/net/dev`. macOS runs `vm_stat` and `netstat -ibn`.
- No root access needed.

## Gotchas

- On platforms other than Linux and macOS, network throughput is omitted rather than shown as zero.
- The CPU figure comes from cumulative `os.cpus()` counters, which count from boot.