> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipways.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitoring and thresholds

> What the agent reports, what it means, and when it becomes somebody's problem.

The agent reports CPU, memory and disk on every heartbeat. A server's
**Monitoring** tab charts them and is where you set what counts as too much.

Samples are kept for **7 days**. A week covers "was it like this last Tuesday"
and the weekend either side of a change; past that nobody is reading a
five-minute reading.

## What the three numbers mean

**CPU** is the load average over the last minute as a share of the core count.
It is not sampled processor time. A machine reading 100% is one where work is
**queuing**, which is not the same as one that is out of capacity — and it
matters when you are deciding what to set the threshold to.

**Memory** is what is in use, not counting what the kernel would hand back on
demand. Cache and buffers do not count against it, so a healthy Linux box does
not read as full.

**Disk** is used space on the root filesystem. A full disk stops deployments,
logs and databases at the same time, which is why its default threshold is the
lowest of the three.

## Thresholds

Defaults are 90% for disk, 90% for memory and 95% for CPU. Set a server's own
where the default is wrong for it — a machine that is meant to sit at 95% CPU
should not be telling you so every five minutes.

A change is applied by the next check, which runs every five minutes.

Crossing a threshold [opens an alert](/alerts). It stays open while the
condition holds and resolves itself when the reading comes back down.

## Deployments on the chart

Every release deployed to **any site on the machine** is marked on the time
axis, and each chart on a deployment's own page shows the hour either side of
it with the two averages.

This is a coincidence, not a cause, and the page is built to keep you on the
right side of that. Alongside the numbers it tells you how many other releases
landed in the same window, how many other sites share the machine being
measured, and how many readings each average came from. A side with fewer than
three readings gets no average at all rather than a thin one.

A deployment that failed is still marked, more faintly: it ran a build on the
machine, which costs CPU, but it never started serving anything.

## What else to measure

Beyond the three, the agent can be asked for four more things. Every one of
them is **off until you turn it on**, per server, because every one of them
costs the machine something — the panel prints what, next to the switch. A
fleet that upgrades and changes nothing measures exactly what it measured
before.

| Collector          | What it costs                                                                                                                                                                       |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PHP-FPM pool**   | One request a minute to the pool status page. Needs `pm.status_path` on the pool and a matching `location` in nginx.                                                                |
| **nginx requests** | Reads the access log once a minute from where it left off, so the cost follows traffic rather than log size. The standard log formats only.                                         |
| **Slow queries**   | Reads the slow query log — which you switch on in the database yourself. That log is the expensive part: a write for every query over the limit, on the path that was already slow. |
| **Queue depth**    | Two Redis commands per watched queue per minute. Redis queues only.                                                                                                                 |

Changes reach the machine on the agent's next heartbeat, within a minute.

Two things about these are worth knowing before you read the charts. The
**front of the queue** is timed from when the agent first saw that job there,
so it reads from zero after an agent restart — low rather than wrong. And the
breakdowns — which queue is deep, which query was worst — are kept only for the
**current** reading. The history keeps the totals, so you can see that queues
were deep an hour ago and not which queue it was.

Slow queries are counted against the threshold on this page rather than the
one the database is set to, so the number on the chart is the number the page
says it is however the database was left configured.

## When the agent is quiet

An agent that has not reported for **two minutes** means the server is treated
as unreachable, and an alert opens for that.

While it is quiet the readings on the page are whatever it last said, not what
the machine is doing now, and thresholds are not measured at all. The page says
so rather than showing a stale chart as though it were live.