Host monitors

What a host monitor is

A host is a machine that sends its system metrics to Uptiva with the OpenTelemetry Collector. Uptiva checks five values (CPU, memory, disk, load and process count) against thresholds you set, and marks the host down when one stays past its threshold or when the host stops sending data. Hosts have their own page under Hosts. They do not use monitor slots.

Availability. Host monitoring is not open to every account yet. For now it is only available to selected accounts.

Requirements

• A Linux, macOS or Windows machine that can reach https://uptiva.linuxmaster.cloud over HTTPS.
• The OpenTelemetry Collector contrib distribution (otelcol-contrib), which includes the hostmetrics receiver. The core distribution does not.
• A plan that includes hosts (see Plan limits).

Set up (Linux, one command)

1. Open /app, go to Hosts and click Add host. Enter a name and, if you like, change the checks and window.
2. On the next screen, open the Linux (one command) tab and run the command on the machine. It already contains your host token, which is shown only once:

curl -fsSL https://uptiva.linuxmaster.cloud/api/install/host.sh | sudo UPTIVA_TOKEN=uph_YOUR_TOKEN sh

The script needs root and a Linux machine with systemd (amd64 or arm64). It downloads otelcol-contrib from the official OpenTelemetry releases and checks its SHA-256 before installing, creates an unprivileged uptiva-collector user, writes the config to /etc/uptiva-collector/config.yaml (readable only by that user) and starts the uptiva-collector systemd service. Running it again with a new token reconfigures and restarts the service. Add --dry-run to print what it would do without changing anything, or --interval 1m to change the sample interval (default 30s).

Check that it runs: journalctl -u uptiva-collector -f. After a minute or two the host shows Waiting for data until the first sample arrives, then first data appears and the status becomes Operational.

To remove it (service, files and user):

curl -fsSL https://uptiva.linuxmaster.cloud/api/install/host.sh | sudo sh -s -- --uninstall

Manual / Docker Compose

On macOS, Windows or any machine without systemd, install otelcol-contrib for your system from the OpenTelemetry Collector releases (github.com/open-telemetry/opentelemetry-collector-releases), save the config from the host page as a file, and run otelcol-contrib --config=host-config.yaml. Run it as a service so it survives reboots. The config has this shape (use the one from the host page; it has the right token):

receivers:
  hostmetrics:
    collection_interval: 30s
    scrapers:
      cpu:
        metrics:
          system.cpu.utilization: {enabled: true}
      memory:
        metrics:
          system.memory.utilization: {enabled: true}
      filesystem:
        metrics:
          system.filesystem.utilization: {enabled: true}
      load:
      processes:
exporters:
  otlphttp:
    endpoint: https://uptiva.linuxmaster.cloud/api/ingest/otlp
    encoding: json
    headers:
      x-oneuptime-token: uph_YOUR_TOKEN
service:
  pipelines:
    metrics:
      receivers: [hostmetrics]
      exporters: [otlphttp]

Docker. Use the Docker tab on the host page, or do it by hand. In a container the collector must read the host's files, not its own, so the config needs root_path: /hostfs under hostmetrics (right after collection_interval):

receivers:
  hostmetrics:
    collection_interval: 30s
    root_path: /hostfs
    scrapers:
      # ... same scrapers as above

Save the full config as otel-config.yaml and this as docker-compose.yml in the same folder:

services:
  uptiva-collector:
    image: otel/opentelemetry-collector-contrib:0.163.2
    container_name: uptiva-collector
    restart: unless-stopped
    pid: host
    command: ["--config=/etc/otelcol/config.yaml"]
    volumes:
      - ./otel-config.yaml:/etc/otelcol/config.yaml:ro
      - /:/hostfs:ro,rslave

Start it with docker compose up -d and follow the log with docker logs -f uptiva-collector.

Samples are sent every 30 seconds as OTLP/HTTP with a JSON body. Only metrics whose names start with system. are kept; everything else is dropped.

The five checks

Each check can be switched off. A host with no enabled check is only watched for missing data.

Evaluation window

Choose a window of 1, 5, 10, 15, 30 or 60 minutes (default 1 for new hosts; 1 minute reacts fastest).

• A check fires when its metric stays past the threshold for the whole window. One spike does not alert.
• A host that stops sending data is marked down after the window, but never sooner than about 90 seconds (the collector sends every 30 seconds). With a 1-minute window that is about 90 seconds, with 5 minutes it is 5 minutes.
• Threshold checks are evaluated every minute, so a breach usually shows 1 to 2 minutes after the window has filled.

The host recovers as soon as one healthy sample arrives: every enabled check at or under its threshold. This normally takes one to three minutes. Alerts, channels and quiet hours work as described in Alerts.

Token handling

• Each host has its own token starting with uph_. It is shown once, when the host is created. Only a hash is stored, so Uptiva cannot show it again.
• Treat it like a password: keep it in the collector config with restricted file permissions, not in a repository. The installer does this for you (mode 0600, owned by the service user).
• If it is lost or leaked, open the host page and click Rotate token. You get a new token and config; the old token stops working immediately, so update the collector right away.
• The token only lets a collector send metrics for that one host.

Plan limits

• Pro: 2 hosts. Business: 5 hosts. Free has none. More hosts can be added with add-ons.
• Hosts do not count toward your monitor limit and do not use monitor slots.
• If your plan changes and you have more hosts than it allows, the extra hosts are suspended. They come back when you are under the limit again.
• For now, host monitoring is only available to selected accounts.

Troubleshooting

If the host stays on Waiting for data, check these first: