# docker

The docker plugin reports every container on the host, running or stopped, grouped by compose project. It sends state, health, CPU, memory, restart count and network and disk I/O rates per container. Turn it on for any host that runs Docker or Podman.

## Enable it

Add `docker` to the `plugins` array.

```json
{
  "plugins": ["docker"],
  "docker": {
    "refreshInterval": 60000,
    "dockerBin": "docker",
    "projects": [],
    "exclude": []
  }
}
```

| Option | Default | What it does |
|---|---|---|
| `refreshInterval` | `60000` | Milliseconds between reports. The plugin sends one report at startup, then one per interval. |
| `dockerBin` | `"docker"` | The CLI to run. `bin` is accepted as an alias. Set it to `podman` for Podman. |
| `projects` | `[]` | If set, report only these compose projects. |
| `exclude` | `[]` | Compose projects to skip. |

`projects` and `exclude` match the compose project name. A container started without compose is its own group, named after the container, so you filter it by container name.

## What it reports

One payload per compose project, with unique id `docker-<project>`.

- `project`, `host` (the machine hostname), `engine: "docker"`, `running` and `total` counts.
- `containers`, one entry per container:
  - `name`, `service` (the compose service name), `image`, `state`, `status` (Docker's text, such as `Up 2 days (healthy)`), `running`.
  - `health` is `healthy`, `unhealthy`, `starting` or empty, parsed from the status text.
  - `cpu` in percent of one core, `mem` and `memLimit` in bytes, `memPercent`.
  - `restarts` and `exitCode` from `docker inspect`.
  - `netIn`, `netOut`, `blkRead`, `blkWrite` in bytes per second. These appear from the second report on.
  - For up to five unhealthy containers, `healthOutput` (the last failing healthcheck's output, with curl's progress meter stripped), `healthFailingStreak` and `healthExitCode`.

I/O rates come from the kernel where possible, from `/proc/<pid>/net/dev` and the cgroup v2 `io.stat`. If those can't be read, the plugin falls back to `docker stats`, which rounds to three significant figures. A container on host networking reports zero network traffic.

## When it alerts

| Condition | Severity |
|---|---|
| Any container has `health` = `unhealthy` | error |
| Any container is stopped with a non-zero `exitCode` | error |
| Any container is stopped with exit code 0 | warning |

The reason names up to two containers and counts the rest, for example `web: api unhealthy after 3 failed checks: curl: (7) Failed to connect`. A healthcheck exit code of -1 reads as `healthcheck timed out`. More than two restarts adds `, N restarts`.

A new problem does not notify on the first bad report. The server holds it until a second consecutive report from the same project is still bad. When the project reports clean again, the server resolves the alert.

### Clustered services

If a cluster rule names this project, the cluster judges it across its member hosts instead.

- A rule with no container name hands the whole project to the cluster. The host sends no alert for it.
- A rule with `match_container` removes only those compose services from this host's check. The other containers in the project still alert as normal.

## On the dashboard

One card per compose project, labelled `Docker · <host>`, with one unit per container.

| Reading | Source | Warn | Crit |
|---|---|---|---|
| RUNNING | `running/total` | fewer running than total | none |
| CPU | sum of container `cpu`, shown in cores | above 2 cores | above 3 cores |
| MEM | sum of container `mem` | none | none |
| NET | sum of `netIn + netOut` | none | none |
| DISK I/O | sum of `blkRead + blkWrite` | none | none |

Each container unit is red when unhealthy or stopped with a non-zero exit code, and amber when stopped cleanly or when its health is `starting`. Containers that are not green also appear in the card's event list, up to eight.

CPU pressure raises the card color for display only. A project that has not reported for 300 seconds shows `OFFLINE`. A clustered project that is not placed on this host shows `STANDBY · <cluster>`.

## Requirements

- The `docker` (or `podman`) CLI on the PATH, or a full path in `dockerBin`.
- The agent user must be able to reach the engine. For Docker that means root or membership in the `docker` group.
- Exact I/O counters need read access to `/proc/<pid>` and `/sys/fs/cgroup`, on cgroup v2. Without them the plugin uses the rounded `docker stats` figures.

## Gotchas

- The plugin checks for the engine once, at startup. If the engine is not up yet, the plugin stays idle until the agent restarts.
- A stopped container with exit code 0 is a warning, not silence. Remove one-shot containers or exclude their project if they exit by design.