User guideWayseer 0.30.0Contents

Docker and Podman

The docker module reads a Docker engine, or Podman through its Docker-compatible API: the engine's host, its containers, images, networks and volumes, and compose projects with their services. Running containers have CPU, memory, network and disk series, and the engine's events (a container starting, exiting, running out of memory, changing health or restarting) show as they happen. It only reads, and needs no license key.

Configuration

modules:
  - kind: docker
    name: docker

With no options, Wayseer reads the engine DOCKER_HOST names, as the docker command does. Without DOCKER_HOST, it tries each place an engine usually listens, in turn, and reads the first one there:

Where	Whose
`/var/run/docker.sock`	Docker, and Docker Desktop with its default socket
`$XDG_RUNTIME_DIR/docker.sock`	rootless Docker
`$XDG_RUNTIME_DIR/podman/podman.sock`	rootless Podman (`systemctl --user enable --now podman.socket`)
`/run/podman/podman.sock`	Podman as root
`~/.docker/run/docker.sock`	Docker Desktop on macOS
`//./pipe/docker_engine`	Docker Desktop on Windows; then Podman's `podman-machine-default` pipe

A socket that appears later, such as an engine started after Wayseer, is found on the next read. To read one engine in particular, name it with host:

modules:
  - kind: docker
    name: podman
    options:
      host: unix:///run/user/1000/podman/podman.sock

Reading /var/run/docker.sock needs your user in the docker group. The engine's socket gives whoever can open it full control of the engine; Wayseer only ever reads through it, with GET requests, and offers no actions.

An engine over TCP

host: tcp://<host>:<port> reads an engine on another machine. Docker's TCP port should use TLS: set ca_file to the CA that signed the engine's certificate and, if the engine checks clients, cert_file and key_file to your client certificate and its key:

options:
  host: tcp://build1.example.com:2376
  ca_file: ~/.docker/build1/ca.pem
  cert_file: ~/.docker/build1/cert.pem
  key_file: ~/.docker/build1/key.pem

tls: true uses TLS with the system's certificates instead. A DOCKER_HOST with DOCKER_TLS_VERIFY and DOCKER_CERT_PATH set is read the way the docker command reads it. ssh:// hosts are not supported; forward the engine's socket and point host at it instead.

The options below go under options.

host

The engine's address: unix:///path, npipe:////./pipe/name or tcp://host:port.

Type: string

Default: DOCKER_HOST, else the first socket found

ca_file

PEM certificates to trust, for a tcp:// host with TLS.

Type: string

Default: the system's

cert_file

A client certificate, for an engine that asks for one, with key_file.

Type: string

key_file

The client certificate's key.

Type: string

tls

Use TLS with a tcp:// host; on when ca_file or cert_file is set.

Type: bool

Default: false

interval

How often the engine is read in full, besides each event, 1s to 1h.

Type: duration

Default: 30s

stats_interval

How often containers in view are sampled, 1s to 5m.

Type: duration

Default: 10s

max_containers

The most containers shown, running ones first, and as many images, networks and volumes, 1 to 100000.

Type: integer

Default: 2000

max_sampled

The most containers sampled at once, those last in view, 1 to 500.

Type: integer

Default: 50

What it shows

host

engine (docker or podman), version, api_version, os, kernel, arch, cpus, memory

One for each: the engine

Name: the engine's host name

container

id, image, state, created, ports, health, exit_code, compose.project, compose.service, and label.<key> for each label

One for each: container

Name: its name

docker/image

id, tags, size, created

One for each: image

Name: its first tag, or its short ID

docker/network

driver, scope, internal, subnet

One for each: network

Name: its name

docker/volume

driver, mountpoint

One for each: volume

Name: its name

docker/project

working_dir

One for each: compose project

Name: its name

service

compose.project

One for each: compose service

Name: its name

Each container runs_on the engine's host, depends_on its image and the volumes it mounts, and is a member_of each network it is on. A compose project owns its services, and each service owns its containers. Images, networks, volumes and projects run_on the host. The host is named as the engine names its machine, so on Linux it is the same as the host this machine shows when the engine runs where Wayseer does.

A running container is OK, and critical when its health check fails. One that exited with code 0 is unknown, not down, since stopping a container is usual; one that exited with another code is a warning, as are restarting and paused containers. A compose service and project take the worst status of their containers.

Wayseer shows at most max_containers containers, running ones first, and at most as many images, networks and volumes; past it, the module's state says how many were left out. Compose's own com.docker.compose.* labels show as compose.project and compose.service. Labels past the first 64 of a container, and the end of a value longer than 256 bytes, are left out.

Metrics

Metric	Unit	Kinds	Meaning
`cpu.utilisation`	percent	`container`	CPU in use, 100 for one whole CPU, as docker stats shows it.
`memory.used`	bytes	`container`	Memory in use, without the page cache it can drop.
`net.receive`	bytes_per_second	`container`	Bytes received on all its interfaces.
`net.transmit`	bytes_per_second	`container`	Bytes sent on all its interfaces.
`disk.read`	bytes_per_second	`container`	Bytes read from block devices.
`disk.write`	bytes_per_second	`container`	Bytes written to block devices.

A running container's series are sampled from the engine's stats only while a lens shows it: the first query samples it at once, then every stats_interval until no lens has asked for it for two minutes, or three times stats_interval if that is longer, or it stops. At most max_sampled containers are sampled at once, those asked for most recently. Each series keeps its last 360 samples, an hour at the default interval, and is forgotten when sampling stops, so a container's history starts when you look at it. CPU, network and disk are rates between samples, so they start from the second sample.

Events

Stream shows these events of each container, as the engine reports them:

Kind	Severity	Says
`start`	info	`web-1 started`
`die`	info for exit code 0, else warning	`worker exited with code 137`, with `exit_code` in its fields
`oom`	error	`worker ran out of memory`
`health_status`	warning when unhealthy, else info	`api is unhealthy`, with `health` in its fields
`restart`	info	`web-1 restarted`

Any change the engine reports, to a container, image, network or volume, is read within a moment, besides the full read every interval. Health checks' own exec events are left out.

Health

"found no Docker or Podman socket"

Start the engine, or set host to where it listens.

"permission denied on /var/run/docker.sock"

Add your user to the docker group and log in again, or use rootless Docker or Podman's socket.

"nothing listens on …" or "connection refused"

The engine is not running there; start it, or check host.

"HTTP 400: client version 1.47 is too old"

The engine is newer than Wayseer knows; update Wayseer.

"the certificate is not trusted; set ca_file"

Set ca_file to the CA that signed the engine's certificate.

"N containers left out past max_containers"

Raise max_containers, or leave it if the running ones are enough.

When the engine stops answering, its host shows as down and everything else from it as unknown, "engine unreachable", until it answers again. Wayseer tries again after a second, then waits twice as long each time, up to 30 seconds, and reconnects to the event stream the same way.

Wayseer asks for Engine API version 1.47, or the engine's own version if that is older, as /_ping names it, so older engines and Podman's Docker-compatible API answer too.