Linux host monitoring with OpenTelemetry

The OpenTelemetry Collector’s hostmetrics receiver reads CPU, memory, disk, filesystem, network, and load statistics directly from the host and exports them to Osuite over OTLP. You run the Collector as a systemd service so it starts on boot and restarts on failure.

Prerequisites

• A Linux host running a systemd-based distribution (Debian, Ubuntu, RHEL, CentOS, Fedora, Amazon Linux).
• root or sudo access to install a package and manage the service.
• Your Osuite ingest endpoint and token.

Set up the Collector

1. Install the Collector as a service. Install the contrib distribution, which includes the hostmetrics receiver and the resourcedetection processor. The package registers a systemd service named otelcol-contrib and writes a default config to /etc/otelcol-contrib/config.yaml.

   Debian / Ubuntu

   OTELCOL_VERSION="0.156.0"
   curl -fsSLO https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v${OTELCOL_VERSION}/otelcol-contrib_${OTELCOL_VERSION}_linux_amd64.deb
   sudo dpkg -i otelcol-contrib_${OTELCOL_VERSION}_linux_amd64.deb

   RHEL / CentOS / Fedora

   OTELCOL_VERSION="0.156.0"
   curl -fsSLO https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v${OTELCOL_VERSION}/otelcol-contrib_${OTELCOL_VERSION}_linux_amd64.rpm
   sudo rpm -ivh otelcol-contrib_${OTELCOL_VERSION}_linux_amd64.rpm

   On 64-bit ARM hosts, replace amd64 with arm64 in the file name.

2. Configure the receiver, processor, and exporter. Replace the contents of /etc/otelcol-contrib/config.yaml with the following. Every scraper listed here is wired into the metrics pipeline, and the resourcedetection processor attaches host identity so each metric is attributable to the machine that produced it.

   receivers:
     hostmetrics:
       collection_interval: 30s
       scrapers:
         cpu:
         memory:
         disk:
         filesystem:
         network:
         load:
   
   processors:
     resourcedetection:
       detectors: [env, system]
       system:
         hostname_sources: [os]
     batch:
   
   exporters:
     otlp/osuite:
       endpoint: ingest.<region>.osuite.io:443
       headers:
         x-osuite-ingest-token: <your-ingest-token>
   
   service:
     pipelines:
       metrics:
         receivers: [hostmetrics]
         processors: [resourcedetection, batch]
         exporters: [otlp/osuite]

3. Restart the service.

   sudo systemctl restart otelcol-contrib
   sudo systemctl status otelcol-contrib

Note

Because the Collector runs directly on the host, it reads /proc and /sys in place and no root_path setting is needed. The root_path option is only required when the Collector runs inside a container with the host filesystem bind-mounted — see Docker container metrics.

Tip

On a cloud VM, add the matching cloud detector to attach instance identity. For example, detectors: [env, ec2, system] on AWS, or gcp / azure on the other providers. The detector adds attributes such as the instance ID, region, and availability zone.

Validate

Confirm the service is running and exporting:

sudo systemctl status otelcol-contrib
sudo journalctl -u otelcol-contrib -f

A healthy Collector logs Everything is ready. Begin running and processing data. and shows no OTLP export errors.

Verify in Osuite

What you should see

Host metrics arrive within a minute — check Dashboards → Explore metrics for CPU, memory, disk, filesystem, network, and load metrics. Build a host dashboard to plot utilization per host.

Data collected

The hostmetrics receiver emits standard system.* metrics. The most useful, by scraper:

Metric	Description
system.cpu.time	CPU time by state (user, system, idle, wait).
system.cpu.utilization	Fraction of CPU time by state.
system.memory.usage	Memory used, by state (used, free, cached, buffered).
system.memory.utilization	Fraction of memory used, by state.
system.disk.io	Bytes read from and written to each disk.
system.disk.operations	Read and write operations per disk.
system.filesystem.usage	Bytes used and available per mounted filesystem.
system.filesystem.utilization	Fraction of each filesystem used.
system.network.io	Bytes received and transmitted per interface.
system.network.packets	Packets received and transmitted per interface.
system.cpu.load_average.1m	One-minute load average.
system.cpu.load_average.5m	Five-minute load average.
system.cpu.load_average.15m	Fifteen-minute load average.

Troubleshooting

If a scraper reports no data, confirm the Collector’s service user can read the source: the filesystem and disk scrapers need read access to /proc and /sys, which the packaged otelcol-contrib service has by default. If the download 404s, check that the version tag exists in the Collector releases and that the architecture in the file name matches the host.

No data in Osuite after a few minutes? Work through these checks.

• Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
• Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
• Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
• Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
• Network — confirm the host has outbound access to the ingest endpoint on port 443.
• Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.

Next steps

• Windows host monitoring — the same recipe for Windows hosts
• Docker container metrics — per-container metrics from the same host
• Dashboards — build host dashboards from the collected metrics
• Alerts — alert on host CPU, memory, and disk thresholds