Docker Integration

The Docker collector monitors containers and the Docker daemon by connecting to the Docker Engine API via a Unix socket. It collects per-container resource metrics (CPU, memory, network, block I/O), daemon-level configuration, and container inventory. It also reports the Docker server version (e.g., "Docker 28.5.2") via the VersionReporter interface.

Setup

1. Verify Docker socket access

The agent connects to the Docker daemon through the Unix socket (default: /var/run/docker.sock). Ensure the agent process has read access:

# Check the socket exists
ls -la /var/run/docker.sock

# Verify the agent user can access it
sudo -u proxima-agent docker info

If the agent user is not in the docker group:

sudo usermod -aG docker proxima-agent

2. Configure the agent

Add a Docker collector to the agent's config.yaml:

collectors:
  - type: docker

Field	Required	Default	Description
type	Yes	—	Must be docker
name	No	docker	Unique name for this collector instance
socket_path	No	/var/run/docker.sock	Path to the Docker Unix socket

The socket path can also be set via the PROXIMA_DOCKER_SOCKET environment variable.

For non-standard socket locations:

collectors:
  - type: docker
    name: docker-custom
    socket_path: "/run/user/1000/docker.sock"

Metrics collected

The Docker collector reports the following metrics under the docker_ prefix:

Container counts

Metric	Type	Labels	Description
docker_containers	Gauge	state	Number of containers by state (running, exited, created, etc.)

Per-container metrics

Only collected for running containers. Each metric includes container_name and container_id (first 12 chars) labels.

Metric	Type	Unit	Description
docker_container_cpu_seconds_total	Counter	seconds	Cumulative CPU time consumed by the container
docker_container_memory_used_bytes	Gauge	bytes	Memory usage minus cache
docker_container_memory_limit_bytes	Gauge	bytes	Memory limit (omitted if unlimited)
docker_container_network_receive_bytes_total	Counter	bytes	Total bytes received across all interfaces
docker_container_network_transmit_bytes_total	Counter	bytes	Total bytes transmitted across all interfaces
docker_container_block_read_bytes_total	Counter	bytes	Total block device bytes read
docker_container_block_write_bytes_total	Counter	bytes	Total block device bytes written

Computed (dashboard) metrics

These ratios are not emitted by the collector — the backend derives them from the raw metrics above and exposes them on dashboards:

Metric	Type	Unit	Derived from	Description
docker_container_cpu_usage_ratio	Gauge	ratio	rate(docker_container_cpu_seconds_total)	CPU usage ratio (0.0–N for N cores)
docker_container_memory_usage_ratio	Gauge	ratio	docker_container_memory_used_bytes / docker_container_memory_limit_bytes	Memory used / limit (only when a limit is set)

tip

The computed docker_container_cpu_usage_ratio can exceed 1.0 on multi-core systems. A value of 2.5 means the container is using 2.5 cores worth of CPU time.

Configuration collected

The Docker collector implements CollectConfig(), which queries the Docker Engine API to gather daemon and resource information.

Daemon info

Parameter	Category	Description
docker_version	Docker / Daemon	Docker server version
storage_driver	Docker / Daemon	Storage driver (e.g., overlay2)
os_type	Docker / Daemon	Operating system type
architecture	Docker / Daemon	Host architecture
total_containers	Docker / Daemon	Total container count
total_images	Docker / Daemon	Total image count

Images

Each image with a valid repo tag is listed under Docker / Images with its size in MB.

Volumes

Each named volume is listed under Docker / Volumes with its driver and mount point.

Networks

Each Docker network is listed under Docker / Networks with its driver, scope, and subnet (if configured).

Container inventory

The agent also discovers Docker containers as part of host inventory collection. Container inventory includes:

• Container ID, name, and image
• Current status and state
• Port mappings (stored as JSONB)
• Creation timestamp

Containers are stored in the host_containers table and accessible via GET /api/v1/hosts/{hostID}/containers.

Version detection

The collector calls docker info via the Engine API during config collection. The server version is reported via the VersionReporter interface and displayed as a version badge on the Integration Detail Page and Host Detail Page.

Troubleshooting

Permission denied

failed to init collector, skipping: create docker client: ...

• The agent user cannot access the Docker socket
• Add the agent user to the docker group: sudo usermod -aG docker proxima-agent
• Or set the correct socket path in socket_path config

Docker not running

If Docker is not running, the collector will fail to initialize. Check Docker status:

systemctl status docker

Socket not found

If using a non-standard socket location, set the socket_path in the collector config or the PROXIMA_DOCKER_SOCKET environment variable.

Checking status

View the collector status in the Proxima Console UI:

1. Navigate to Integrations to see all hosts and their status
2. Click on the Docker integration to view the detail page
3. Or go to a specific Host and check the Integrations tab for per-host status
4. Green = ok, Red = error, Gray = unknown