Docker

The Middleware Infrastructure Agent can run as a Docker container to collect host metrics, container metrics, and configured logs from your Docker environment.

Use the collected CPU, memory, network, and container-status data to investigate resource usage and unhealthy containers without installing the Agent directly on the host operating system.

How it works#

The Middleware Infrastructure Agent runs as a container on your Docker host and collects telemetry using:

Docker daemon: Collects container information and resource metrics through the Docker API.
Host filesystem mounts: Accesses host and container information required for monitoring.
Log collection: Collects container logs through configured host volume mounts.
Telemetry endpoints: Exposes ports 9319 and 9320 for receiving OpenTelemetry data.

You can install the Agent using the installation script or Docker Compose.

Prerequisites#

Before installing the Middleware Docker Agent, verify the following requirements:

Note: Run only one Middleware Infrastructure Agent per Docker host to avoid duplicate telemetry collection and configuration conflicts.

Installation#

1 Get your Middleware credentials#

Log in to your Middleware account.
Go to Installation → Docker.
Copy the installation command containing your API key and target URL.

Alternatively, use the following command and replace the placeholders with your account details.

2 Install the Docker Agent#

Run the following command on your Docker host:

1MW_API_KEY="<MW_API_KEY>" \
2MW_TARGET="https://<MW_UID>.middleware.io:443" \
3bash -c "$(curl -fsSL https://install.middleware.io/scripts/docker-install.sh)"

The installation script deploys the Middleware Infrastructure Agent as a Docker container.

Replace:

Variable	Description
`MW_API_KEY`	Your Middleware API key
`MW_TARGET`	Your Middleware target URL, including port 443

3 Add custom host tags (optional)#

To associate custom tags with your Docker host, set the MW_HOST_TAGS environment variable during installation.

Specify multiple tags as comma-separated key:value pairs.

1MW_HOST_TAGS=env:prod,role:web \
2MW_API_KEY="<MW_API_KEY>" \
3MW_TARGET="https://<MW_UID>.middleware.io:443" \
4bash -c "$(curl -L https://install.middleware.io/scripts/docker-install.sh)"

After installation, verify the configured tags in the Middleware UI:

Infrastructure → [Your Host] → System Information

4 Verify the Agent installation#

Check whether the Middleware Agent container was created and is running:

1docker ps -a --filter ancestor=ghcr.io/middleware-labs/mw-host-agent:master

Check the container status:

Up — The Agent container is running.
Exited — The Agent container was created but is no longer running. Check its logs to identify the issue.
Blank output — No matching Agent container was found. Review the installation output for errors.

If the container is not running, check its logs:

1docker logs <container_id>

5 Verify data collection#

After the Agent is running:

Log in to Middleware.
Go to Infrastructure Monitoring → Hosts.
Verify that your Docker host appears with a recent Last Seen timestamp.
Open Infrastructure Monitoring → Containers to view collected container metrics.

Data typically starts appearing within a few minutes after installation.

After data collection starts, you can:

View host and container metrics in Infrastructure Monitoring.
View collected container logs in Log Monitoring.
Create alerts for CPU, memory, network usage, and other collected metrics.
Create custom dashboards to monitor Docker container performance.

Install using Docker Compose#

You can also deploy the Middleware Infrastructure Agent using Docker Compose.

Use this method if you manage Docker services through Compose files or want to configure the Agent's ports, volumes, and restart policy directly.

1 Create a Docker Compose file#

Create a file named docker-compose.yml and add the following configuration:

1version: "3.8"
2
3services:
4  mw-host-agent:
5    image: ghcr.io/middleware-labs/mw-host-agent:master
6    restart: unless-stopped
7    environment:
8      - MW_API_KEY=<MW_API_KEY>
9      - MW_TARGET=https://<MW_UID>.middleware.io:443
10    ports:
11      - "9319:9319"
12      - "9320:9320"
13    volumes:
14      - /var/run/docker.sock:/var/run/docker.sock:ro
15      - /proc:/host/proc:ro
16      - /sys/fs/cgroup:/host/sys/fs/cgroup:ro

Replace MW_API_KEY and MW_TARGET with your Middleware account details.

Configuration reference#

Configuration	Description
`image`	Middleware Infrastructure Agent container image
`restart: unless-stopped`	Restarts the Agent automatically unless manually stopped
`MW_API_KEY`	Middleware API key
`MW_TARGET`	Middleware target URL
`9319`	OTLP/gRPC endpoint
`9320`	OTLP/HTTP endpoint
`/var/run/docker.sock`	Provides access to the Docker daemon
`/proc`	Provides host process and system information
`/sys/fs/cgroup`	Provides container resource and cgroup information

Note: Mounting the Docker socket provides the Agent with access to the Docker API. Restrict access to the Agent configuration and container runtime accordingly.

2 Start the Agent#

From the directory containing docker-compose.yml, run:

1docker compose up -d

Verify the container status:

1docker compose ps

The mw-host-agent service should show a running status.

3 Verify data collection#

Go to Infrastructure Monitoring → Hosts and verify that the Docker host is reporting data.

You can also check container-level metrics under Infrastructure Monitoring → Containers.

Troubleshooting#

If the Agent is installed but telemetry does not appear in Middleware, check the following.

Docker socket not found#

If the Agent reports:

1Error: no such file or directory: /var/run/docker.sock

Verify that:

Docker Engine is installed and running.
The Docker socket exists at /var/run/docker.sock.
The Docker socket path has not been customized using DOCKER_HOST.
The Agent has access to the configured Docker socket.

Permission denied on mounted volumes#

If the Agent cannot access required host files or Docker resources:

Verify that the user running the installation has sufficient permissions.
Check permissions for the Docker socket and mounted directories.
Run the installation with the required privileges.

Avoid changing host filesystem permissions broadly to resolve mount errors.

No metrics in Middleware#

If the Agent is running but metrics are not available:

Check network connectivity: Verify that outbound HTTPS traffic to MW_TARGET on port 443 is allowed.
Check API key: Confirm that MW_API_KEY is valid and configured correctly.
Check duplicate Agents: Make sure only one Middleware Infrastructure Agent is running per host.
Check proxy settings: If the host uses a corporate proxy, configure HTTP_PROXY and HTTPS_PROXY as required.
Check Agent logs: Review the container logs for collection or connectivity errors.

Agent container exits immediately#

If the Agent container stops after installation, run:

1docker logs <container_id>

Check the logs for:

Missing or invalid environment variables.
Network connectivity errors.
Docker socket or volume mount permission errors.
Agent initialization failures.

Resolve the reported error and restart the Agent.

Uninstall#

To remove the Middleware Infrastructure Agent installed using the Docker installation script, identify the Agent container:

1docker ps -a --filter ancestor=ghcr.io/middleware-labs/mw-host-agent:master

Stop the Agent container:

1docker stop $(docker ps -a -q --filter ancestor=ghcr.io/middleware-labs/mw-host-agent:master)

Remove the container:

1docker rm $(docker ps -a -q --filter ancestor=ghcr.io/middleware-labs/mw-host-agent:master)

Note: These commands target containers using the specified Middleware Agent image. Verify the matching containers before removing them.

Uninstall Docker Compose deployment#

If you installed the Agent using Docker Compose, run the following command from the directory containing docker-compose.yml:

1docker compose down

This stops and removes the services and networks created by that Compose project.

Collected metrics#

The Middleware Docker Agent collects container metrics across the following categories:

Category	Example metrics	Description
CPU	`container.cpu.utilization`, `container.cpu.usage.total`	CPU utilization and usage
Memory	`container.memory.usage.total`, `container.memory.percent`	Memory consumption and utilization
Network	`container.network.io.usage.rx_bytes`, `container.network.io.usage.tx_bytes`	Network traffic and packet statistics
Disk I/O	`container.blockio.io_service_bytes_recursive`	Container disk I/O activity
Processes	`container.pids.count`, `container.pids.limit`	Process count and configured limits
Container status	`container.status`, `container.uptime`	Container state and uptime
Restarts	`container.restarts`	Number of container restarts

Note: Some metrics are available only with specific cgroup versions. For example, several Block I/O and memory metrics require cgroups v1, while others require cgroups v2.

For the complete list of supported metrics, retain the existing Collected Metrics reference table.

Need assistance or want to learn more about Middleware? Get in touch with us via our Contact Us or join our Slack channel.