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

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

2 (Optional) Add host tags:#

Your API Keys

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/deb-install.sh)"

3 Verify installation#

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

1 Run the Installer:#

Your API Keys

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

2 (Optional) Add host tags:#

Your API Keys

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/rpm-install.sh)"

3 Verify installation#

1sudo systemctl status mw-agent
2sudo 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 Proxy users under 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:

1MW_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:

1sudo mw-agent services list

1SERVICE ID         SERVICE NAME               LANGUAGE   TYPE      PORTS   INSTANCES   INSTRUMENTED
2e6f38b1db677d920   book-service-java          java       systemd   8086    1           -
39fff4fcb924d5413   book-service-java-docker   java       docker    8086    1           -
48d3392312658de2e   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:

1sudo 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#

1sudo 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).

1sudo 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:

1sudo 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#

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

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

Troubleshooting#

Data is not coming after agent installation?

It may take a few moments for telemetry to appear after a new Agent installation. First, go to Infrastructure Monitoring → Hosts and check whether the host is reporting data.

If the host does not appear or data is not being collected, check the following:

• Check network connectivity. Verify that the host can establish an outbound HTTPS connection to: https://<YOUR_UID>.middleware.io:443

• Check for multiple Agents. Make sure only one Middleware Infrastructure Agent is running on the host.

• Check Agent logs. Review the Agent log file for errors: /var/log/mw-agent/mw-agent.log You can also inspect the service logs using journalctl.

• Check proxy configuration. If the host is behind a corporate proxy, verify that the required HTTP_PROXY and HTTPS_PROXY environment variables are configured correctly and that the proxy allows connections to Middleware.

• Check permissions. Make sure the installation and Agent management commands are run with sufficient privileges. Use sudo where required.

• Deep troubleshooting. For deeper troubleshooting, see the MW Linux Agent Troubleshooting Guide.

If you’re still unsure about the issue, you may reach out to Middleware support team via the chatbot (which you are seeing at the bottom-right corner of this page) or email support{at}middleware{dot}io