Edge Agent synchronization lag during container state changes

Answer

The Edge Agent’s reporting frequency is governed by two environment variables:

• PORTAINER_AGENT_POLL_INTERVAL – how often the agent queries the local Docker daemon for container state changes (default 10 seconds).
• PORTAINER_AGENT_HEARTBEAT – how often the agent sends a heartbeat/payload to the Portainer server (default 30 seconds).

When a container state change is detected during a poll, the agent notifies the server immediately; the heartbeat interval only affects how frequently the agent reports that it is still alive.

Confirmed facts

• The poll interval detects changes; the heartbeat interval does not affect detection latency.
• Both variables are set at container start‑up; there are no runtime flags or API calls to modify them.
• Lowering PORTAINER_AGENT_POLL_INTERVAL reduces lag but increases CPU usage and outbound traffic proportionally.
• The agent’s outbound traffic per poll is a small JSON payload, so modest reductions (e.g., to 5 seconds) typically stay within typical edge‑network bandwidth limits.

Steps to adjust the interval

1. Stop the existing Edge Agent container (if running).
2. Start a new container with the desired values, for example:

docker run -d \
  --name portainer_agent \
  -e PORTAINER_AGENT_POLL_INTERVAL=5 \
  -e PORTAINER_AGENT_HEARTBEAT=15 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  portainer/agent:latest

1. Verify the settings:

docker inspect portainer_agent | grep -i POLL_INTERVAL
docker inspect portainer_agent | grep -i HEARTBEAT

1. Check that heartbeats appear at the expected frequency in the logs:

docker logs -f portainer_agent | grep -i heartbeat

1. Optionally, measure network traffic before and after the change (e.g., with tcpdump or Wireshark) to ensure traffic remains acceptable.

When to ask for more detail

If you observe that changing the poll interval does not affect the lag you see, you would need to know the current value of PORTAINER_AGENT_POLL_INTERVAL (or whether the agent is running with the updated environment) to determine whether the change was applied correctly.