How to monitor Docker containers with Compose

You monitor Docker containers with inping by adding the agent as a service to your project's Compose file. For every service it reports CPU, memory, network, disk I/O and whether it is running, plus the values of the host. If a service is down, an alert opens with the next report. The agent reaches the Docker socket only through a proxy that rejects every write.

What do you see afterwards?

• Services: one row per service of the Compose project with state, CPU, memory, network and I/O. The rates appear within two intervals, because they need two measurements.
• The host: CPU, memory, load and disks, read through read-only mounts of /proc, /sys and /.
• Project → Packages: the packages from the lock files of the mounted project directory.

Not reported in a container: host packages and scheduled tasks (they would be the container's), runtime versions such as php -v (they cannot be queried across container boundaries) and packages inside the images of other services.

What should you keep an eye on with containers?

• Is it running at all? The state is Docker's running state. A container in a restart loop counts as not running whenever a measurement catches it restarting. A container that runs but no longer responds still counts as running. So also check web services from the outside with an HTTP(S) check on the URL.
• Memory against the limit: inping relates memory without file cache to the container's limit, or to the host's memory if there is no limit. When a container reaches its limit, the kernel ends processes inside it. An alert beforehand is worth more than a restart afterwards.
• CPU: inping shows the share of the whole host CPU (0 to 100), not per core like docker stats. This way the containers add up against the usage of the host.
• The host's disks: logs and volumes live on the host and fill its disk. So the rule for disks applies here too.

Requirements

• Docker Engine with Compose v2 on the host, and the project's docker-compose.yml
• outgoing HTTPS to www.inping.io and to ghcr.io
• a free inping account and a registration token (valid for 24 hours)
• the image version and digest from the release notes in the app under Agents → Installation and downloads (/agents/install)

Step by step

The Docker tab in the Agents → Add agent dialog shows all three parts with your values. Here you see placeholders.

1. Three lines in the .env next to the Compose file

INPING_AGENT_IMAGE=ghcr.io/medienakzent/inping-agent:<version>@sha256:<digest>
INPING_API_URL=https://www.inping.io
INPING_PROJECT_ID=<project-id>

The image is pinned to a version and digest. There is no moving tag such as latest: this way a tampered registry cannot swap the agent on pull.

2. Services, config, volume and network in the Compose file

Add the following parts to the project's Compose file. The agent runs with a read-only file system, without capabilities and as user 65532; it can only write to the volume inping-agent-state.

services:
  inping-agent:
    image: ${INPING_AGENT_IMAGE:?set INPING_AGENT_IMAGE to a release}
    restart: unless-stopped
    read_only: true
    cap_drop: [ALL]
    security_opt:
      - no-new-privileges:true
    configs:
      - source: inping-agent
        target: /etc/inping/agent.toml
    volumes:
      - inping-agent-state:/var/lib/inping-agent
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /:/host/root:ro
      - ./:/srv/app:ro
    networks: [default, inping]
    depends_on: [inping-docker-proxy]

  inping-docker-proxy:
    image: tecnativa/docker-socket-proxy:0.3.0
    restart: unless-stopped
    environment:
      CONTAINERS: 1
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks: [inping]

configs:
  inping-agent:
    content: |
      api_url = "${INPING_API_URL:?set INPING_API_URL}"
      state_dir = "/var/lib/inping-agent"

      [docker]
      endpoint = "tcp://inping-docker-proxy:2375"

      [[project]]
      id = "${INPING_PROJECT_ID:?set INPING_PROJECT_ID}"
      path = "/srv/app"

volumes:
  inping-agent-state:

networks:
  inping:
    internal: true

The proxy is not optional: it is the only service that sees the socket, and it sits in the internal network inping. It rejects every write and everything outside /containers. Pin its image by digest too, once you have determined it:

docker buildx imagetools inspect tecnativa/docker-socket-proxy:0.3.0

3. Register once and start

The token goes in through standard input and ends up in no file.

echo "<token>" | docker compose run --rm -T inping-agent register --token -
docker compose up -d

There is one project per Compose file. A second project on the same host gets its own agent in its own Compose file.

Without the socket proxy

The agent can also read the socket directly: with /var/run/docker.sock mounted, group_add with the socket's group and the endpoint unix:///var/run/docker.sock. It then sends the same requests, but anyone who breaks into its container controls the host. Take this route only on a host where nothing else runs alongside the agent, such as your own Synology NAS. The details are in the installation guide, chapter 8.

How do you check that it works?

docker compose ps                        # inping-agent and inping-docker-proxy: Up
docker compose logs --tail 20 inping-agent

The log shows msg=starting, msg=configuration and msg="docker: reporting the agent's own Compose project" project=<name>. In inping the Services section appears on the agent's page. If it is missing, switch on the metric Services (Docker) under Settings → Collected metrics.

Thresholds and alerts

The rule for services is active on every new agent: if a service is not running, an alert opens immediately and closes by itself as soon as the service is running again. On top of that come the host rules for CPU and memory (above 90% for 5 minutes) and disks (above 90% immediately).

You create your own rules on the agent's page under Settings → Alert rules, for one particular service or for all. CPU, memory in per cent or bytes, network and I/O per second are possible. A good start is the memory of a service above 90% for 5 minutes.

For you to hear about it, the assigned project needs a notification rule, for example for Service down, Server threshold exceeded or Agent offline, by mail or webhook. The agent counts as offline after three missed reports.

Update

The agent never replaces itself in a container. Enter the new version and the new digest in the .env and pull the image again:

docker compose pull inping-agent && docker compose up -d inping-agent

Uninstall

Remove the two services, the config, the volume and the network from the Compose file and run docker compose up -d --remove-orphans. With a copy of the example file, docker compose down -v is enough, where -v deletes the state volume. Then delete the agent in inping.

When nothing arrives

• register reports registration failed: the token has expired or been used, or INPING_API_URL is wrong. The message names the response.
• set INPING_AGENT_IMAGE to a release: the .env is not next to the Compose file, or a variable is missing.
• The agent restarts in a loop: look in docker compose logs inping-agent. cannot start means it was never registered (step 3). docker source unusable means the proxy cannot be reached: check that it is attached to the network inping and that the endpoint is tcp://inping-docker-proxy:2375.
• Host metrics arrive, services do not: the proxy answers with 403 because CONTAINERS: 1 is missing. Or the agent's container belongs to no Compose project, in which case every container on the host is reported.
• The project's packages are missing: ./:/srv/app:ro mounts the wrong directory. The lock files have to be at the top level of /srv/app.

Frequently asked questions

Further reading

• All the ways to connect servers and websites to inping
• Monitor a Linux server (the agent directly on the host)
• Monitor a Synology NAS
• Plans and limits for agents
• Full installation guide for all systems