Remote Host Metrics

Remote Host Metrics (remote_host_metrics) collects resources from a Linux machine over SSH. The source agent makes the connection; the remote machine appears in Infrastructure → Machines with its own identity and an SSH badge.

No Python, additional runtime or persistent collector is installed on the remote host. The check streams a read-only shell script over SSH on each run.

What you need

• One enrolled source agent that supports remote_host_metrics and can reach the target’s SSH port. The source agent can run on Linux, Windows or macOS.
• A Linux target with sh, awk, and read access to /proc and /sys.
• An SSH login and a saved password or unencrypted private-key secret.
• The server’s verified SSH host-key fingerprint, obtained from a trusted administrator or the host console.

Root access is not required. Standard stat supplies filesystem capacity, ip adds interface addresses, and systemctl supplies optional systemd service states. Missing optional utilities leave those measurements unavailable while core collection continues. MAC addresses can still be read from sysfs without ip.

Create the check

1. Open Test Management → New test.
2. Under Host / workloads, select Remote Host Metrics.
3. Choose one specific source agent with SSH access to the target. Multiple source agents and network scope, label or cluster pools are not supported.
4. Enter the target hostname or IP, optionally with a port. The default SSH port is 22. Select IPv4 or IPv6.
5. Set the SSH User and Auth method.
6. For password authentication, choose a Password secret. For private-key authentication, choose a Private key secret. Add or manage secrets opens the secret manager without leaving the draft.
7. Enter the Host key fingerprint, then configure the schedule and any processes or services to monitor.
8. Create the test and approve the shared secret’s use by this check and source agent in Manage → Secrets. See shared secrets and access grants for agent delivery requirements and the approval workflow.

The password is stored in the selected secret, not entered into the check’s parameters. Switching authentication methods clears the selected secret so you can choose a matching one. Revoked secrets are not offered.

The Host key fingerprint is required with both authentication methods. It verifies the server’s identity; it is separate from the password or private key used to log in. Host-key verification cannot be disabled for this check.

The default interval is 60 seconds, with a 10-second timeout. The minimum interval is 30 seconds and the maximum timeout is 30 seconds. Use Processes to monitor for up to 32 exact executable names and Services to monitor for up to 16 systemd unit names, such as nginx.service.

Only one Remote Host Metrics check belongs in a test. It can accompany SSH and compatible network diagnostics to the same target. Local Host Metrics and Containers measure the source agent’s own host and cannot be combined with it.

Measurements and results

Each snapshot can include CPU utilization and load, memory and swap, local filesystem capacity and inodes, interface counters and throughput, process resources, disk I/O rates, uptime, and the requested service states.

Remote filesystems, read-only images and container backing mounts are excluded from filesystem capacity. Command lines, process environments and logged-in users are not collected. Restricted access and collection limits are reported as gaps, rather than silently claiming complete coverage.

Rates require two successful samples. A reboot, collection failure or machine identity change resets the baseline. A failed connection produces a failed collection, not zero CPU or memory usage. An unknown service state remains unavailable; a known inactive service reports inactive. Collection success does not mean that every monitored service is healthy.

Find the machine in Infrastructure

After the first successful collection and the next inventory processing pass, open Infrastructure → Machines. The remote machine’s Device tab shows its resources, services, disk I/O, SSH target and collecting agent.

The source agent is recorded as the observer, not as an agent installed on the remote host. NIC evidence can match an existing machine already observed by another source. The SSH connection address alone is not treated as proof that an interface owns that IP address, since the endpoint may be behind NAT.

Reassigning the test to a different single source agent preserves its remote inventory identity. Create a new test when replacing the target with an unrelated machine.

Query remote resources

Scope host-wide queries by the remote check’s test_id. An agent_id identifies the observer and may cover several remote targets as well as its own host.

host_metrics_cpu_percent{test_id="remote-a"}

host_process_cpu_percent{test_id="remote-a"} | max by (host_id,process_name,process_instance)

Replace remote-a with the check ID. Typed host-resource queries expose host_id and test_type to distinguish machines. To restrict an observing agent’s query to its own local resources, filter test_type="host_metrics".

Troubleshooting

• Check type unavailable on an agent: update the source agent to a build that advertises remote_host_metrics.
• No matching password or key secret: create the appropriate SSH secret in Manage → Secrets, then return to the picker.
• Secret denied: confirm shared-secret delivery is enabled on the source agent and approve the exact check/agent grant. Parameter changes require a matching approval.
• Host-key mismatch: verify the server’s current fingerprint through a trusted channel before updating the check and its grant.
• No machine yet: confirm a successful collection, then allow the next inventory pass to process it.
• Missing filesystem, address or service data: check permissions and the related optional utility. Non-systemd hosts cannot report systemd unit state.

For configuring alerts without treating missing data as a healthy result, see health rules.