Linux

The Middleware Infrastructure Agent collects telemetry from Linux hosts so you can monitor resource usage and investigate host performance. Configured log collection and application instrumentation add context from logs and traces.

Use this integration to monitor Linux hosts, including resource utilization, system activity, logs, and application telemetry.

Prerequisites#

1. System Requirements
   • CPU architectures: x86_64 and ARM
   • Memory: ≥ 1 GB (agent uses ~200 MB)
   • Required Tools: curl or wget installed on the host
2. Supported Distributions
   • DEB-based: Ubuntu, Debian
   • RPM-based: Red Hat, CentOS, Fedora, SUSE, Rocky Linux, Oracle Linux, Amazon Linux
   • Other DEB/RPM distros may work but aren’t officially tested.

Note:

• If the host connects to the internet through a proxy, configure the proxy environment variables before running the installation script:, set HTTP_PROXY , HTTPS_PROXY (and lowercase variants)
• Make sure the proxy allows outbound connections to Middleware.

Installation#

DEB-Based Distributions (Ubuntu, Debian)RPM-Based Distributions (Red Hat, Amazon Linux, CentOS, Fedora, etc.)

1 Run the Installer:#

Your API Keys

bash

MW_API_KEY="<MW_API_KEY>" \
MW_TARGET="https://<MW_UID>.middleware.io:443" \
bash -c "$(curl -L https://install.middleware.io/scripts/deb-install.sh)"

2 (Optional) Add host tags:#

Your API Keys

bash

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

3 Verify installation#

bash

sudo systemctl status mw-agent
sudo journalctl -u mw-agent -f    # stream live logs

1 Run the Installer:#

Your API Keys

bash

MW_API_KEY="<MW_API_KEY>" \
MW_TARGET="https://<MW_UID>.middleware.io:443" \
bash -c "$(curl -L https://install.middleware.io/scripts/rpm-install.sh)"

2 (Optional) Add host tags:#

Your API Keys

bash

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

3 Verify installation#

bash

sudo systemctl status mw-agent
sudo journalctl -u mw-agent -f    # stream live logs

Supported Environments#

The Middleware Linux agent is distributed as standard DEB and RPM packages and runs as a regular systemd service. It does not depend on any cloud provider's APIs or services, so it works the same way on any Linux host that runs a supported distribution and can reach your Middleware account over HTTPS, including:

• Public cloud virtual machines and bare metal: Amazon EC2, Microsoft Azure Virtual Machines (including Virtual Machine Scale Sets), Google Compute Engine, Oracle Cloud Infrastructure (OCI) Compute, DigitalOcean Droplets and other cloud providers.
• Private cloud and on-premises: VMware vSphere, Proxmox, KVM, Hyper-V and physical servers.

Use the installer that matches the host's distribution:

Both x86_64 and Arm64 architectures are supported, including Arm-based cloud instances such as AWS Graviton, Azure Cobalt, Google Axion and OCI Ampere.

Network requirements#

The agent sends data to your Middleware account over HTTPS (port 443). Make sure the host's firewall rules, security groups or network security lists allow outbound traffic to https://<YOUR_UID>.middleware.io. Hosts without direct internet access need a NAT gateway or an HTTP proxy (see Prerequisites).

Adding environment metadata#

To filter and group hosts by cloud provider, region or environment in Middleware, add them as host tags using MW_HOST_TAGS when you run the installer, for example:

MW_HOST_TAGS="cloud.provider:oci,cloud.region:sa-santiago-1,env:production"

Using the OpenTelemetry Collector#

If you prefer to run the OpenTelemetry Collector instead of the Middleware agent, the OpenTelemetry Collector Contrib is also supported on any Linux host and can send host metrics, logs and traces directly to Middleware. For managed Kubernetes services such as Amazon EKS, Azure AKS, Google GKE and Oracle OKE, use the Middleware Kubernetes agent.

Zero-Code Instrumentation with OBI#

The Linux agent automatically discovers the applications running on the host, whether they run as host processes, systemd services or Docker containers, and detects the programming language of each one. You can then instrument any discovered application with OpenTelemetry eBPF Instrumentation (OBI).

OBI uses eBPF to capture traces and RED metrics (request rate, errors and duration) for HTTP, gRPC and database calls directly from the Linux kernel. No code changes, application restarts, added packages or image rebuilds are required, which makes it well suited to containerized applications whose images you cannot modify.

Requirements#

• Linux kernel 5.8 or later with BTF enabled, or kernel 4.18 or later on RHEL-family distributions (Red Hat, CentOS, Rocky Linux, Oracle Linux).
• The OBI agent, which the DEB and RPM installers above install automatically on supported kernels. To skip it, set MW_ENABLE_OBI=false when running the installer.

Step 1: Discover applications#

List the applications the agent has discovered on the host, along with their detected language, type (for example, systemd or docker) and listening ports:

sudo mw-agent services list

SERVICE ID         SERVICE NAME               LANGUAGE   TYPE      PORTS   INSTANCES   INSTRUMENTED
e6f38b1db677d920   book-service-java          java       systemd   8086    1           -
9fff4fcb924d5413   book-service-java-docker   java       docker    8086    1           -
8d3392312658de2e   orders-api                 python     docker    8000    1           -

Use --language to filter by language (java, python, node, go, rust, php, ruby) and --all to show each running instance individually.

Step 2: Instrument an application#

Instrument an application with OBI by its service name or service ID:

sudo mw-agent instrument --type obi --language python orders-api

All running instances (replicas) of the same application share a service ID, so they are instrumented together. Traces appear in Middleware under APM → Services within a few minutes.

Remove instrumentation#

sudo mw-agent uninstrument --type obi orders-api

Instrumenting systemd services#

For Java, Python and Node.js applications that run as systemd services, you can also instrument them with the full OpenTelemetry language agent instead of OBI, still without code changes. The DEB and RPM installers install the required OpenTelemetry Injector by default (set MW_ENABLE_INJECTOR=false to skip it).

sudo mw-agent instrument --type systemd --language java book-service-java

This adds a systemd drop-in that loads the language agent into the service, and restarts the service to apply it. To remove it:

sudo mw-agent uninstrument --type systemd book-service-java

Manage the agent (Commands)#

Middleware agent runs as a systemd service in Linux based systems, usually on Linux systems, the Middleware Agent runs as a systemd service. The service definition is typically located under:

/usr/lib/systemd/system/

Use the following commands to start, stop, restart, and check the status of the Middleware Agent.

Verify data collection#

After installing the Agent, allow a few moments for the host to start reporting telemetry.

Go to Infrastructure Monitoring → Hosts and verify that your Linux host appears and is reporting metrics.

After data collection starts, you can:

• View host metrics in Infrastructure Monitoring.
• View collected host logs in Log Monitoring.
• Create alerts for collected metrics.
• Create custom dashboards to visualize Linux host metrics.

Uninstall#

bash -c "$(curl -L https://install.middleware.io/scripts/deb-uninstall.sh)"

bash -c "$(curl -L https://install.middleware.io/scripts/rpm-uninstall.sh)"

Troubleshooting#

It can take a few minutes for a new host to appear. Check Infrastructure Monitoring → Hosts first. If the host doesn't appear or data stops, work through these checks in order.

1. Check that the agent is running#

sudo systemctl status mw-agent

The service should be active (running). If it's restarting or failed, the logs in the next step show why.

2. Read the agent logs#

The agent logs to the systemd journal:

sudo journalctl -u mw-agent -n 200 --no-pager
sudo journalctl -u mw-agent --since "30 min ago" | grep -i -E "error|warn|fatal"

If you set logfile in /etc/mw-agent/agent-config.yaml, the agent writes to that file instead.

3. Check the API key and target#

The installer writes both values to /etc/mw-agent/agent-config.yaml:

sudo grep -E "^(api-key|target):" /etc/mw-agent/agent-config.yaml

• target must be your account URL, https://<YOUR_UID>.middleware.io:443.
• api-key must be your project's ingestion key, not a Public API key. See API Keys.

After changing either value, restart the agent with sudo systemctl restart mw-agent.

4. Check network connectivity#

The host needs outbound HTTPS to your account URL:

curl -sS -o /dev/null -w "%{http_code}\n" https://<YOUR_UID>.middleware.io:443

Any HTTP status code means the host can reach Middleware. A timeout or a DNS or TLS error points to a firewall, security group, DNS or proxy problem.

If the host is behind a proxy, check that the running agent has the proxy variables and that the proxy allows *.middleware.io:

sudo cat /proc/$(pgrep -o -x mw-agent)/environ | tr '\0' '\n' | grep -i proxy

See Prerequisites for how to set them.

5. Check for more than one agent#

Run only one Middleware agent per host. A second agent, for example a containerized one, can cause duplicate or missing data:

pgrep -a mw-agent
sudo docker ps --filter "name=mw-agent" 2>/dev/null

6. Check the APM ports#

Applications in host-agent mode send traces to the agent on port 9319 (OTLP/gRPC) or 9320 (OTLP/HTTP). If APM data is missing but host metrics arrive, check that the agent is listening:

sudo ss -ltnp | grep -E ":(9319|9320)\b"

Another process on these ports stops the agent from receiving APM data.

Still stuck?#

Collect the output of the checks above, without the API key, and contact Middleware support through the chat at the bottom right of this page or at support{at}middleware{dot}io.