peardata/user-guide/containers.md

Containers (Docker)

PearData can chart per-container CPU and memory and show human names (e.g. dozzle) instead of short hashes.

Requirements

On the agent host:

1. Docker (or Podman with a compatible socket) installed
2. Agent user can read the engine socket
3. PEARDATA_DOCKER=1 in the agent .env

The one-line installer does this automatically when Docker is detected:

• Adds peardata to the docker group
• Sets unit SupplementaryGroups=… docker
• Writes PEARDATA_DOCKER=1 and PEARDATA_DOCKER_SOCKET=…

Then restart: sudo systemctl restart peardata.

Already installed without Docker setup?

sudo usermod -aG docker peardata
# /opt/peardata/.env — add or set:
#   PEARDATA_DOCKER=1
#   PEARDATA_DOCKER_SOCKET=/var/run/docker.sock
# Unit must include docker in SupplementaryGroups (re-run installer --server, or edit peardata.service)
sudo systemctl daemon-reload
sudo systemctl restart peardata

Confirm names loaded:

sudo journalctl -u peardata -n 50 --no-pager | grep -i docker

You should see a line like Docker container names loaded with a count.

What you see in the UI

Surface	Behavior
Charts → Containers	Cards titled dozzle · CPU, dozzle · memory; family groups by container name
Card subtitle	Units only (chart id stays in the tooltip for debugging)
Explore dropdown	Human titles, not docker.cpu.<hash>
Cgroup charts	Same name enrichment when the socket is readable

Chart ids remain docker.cpu.<shortId> / docker.mem.<shortId> so history stays stable when a container is recreated with the same id prefix.

How names are loaded (agent)

PearData tries, in order:

1. Docker Engine API over the unix socket (raw HTTP — works under Bare)
2. docker ps CLI
3. On-disk config.v2.json under /var/lib/docker/containers (if readable)

Then each container label prefers:

1. Compose / Swarm / Kubernetes service labels (web, web · 2)
2. Docker Names (e.g. /dozzle → dozzle)
3. Image short name
4. Fallback container <12-char id> if none of the sources worked

If the UI still shows container <hash>, the agent could not reach Docker. Check the journal for Docker container names loaded / Container names loaded for cgroups, then fix group/socket and restart.

Related

• Env: CONFIGURATION.md (PEARDATA_DOCKER*)
• Collector: EXTENDING.md
• Taxonomy section Containers: DASHBOARD.md