How to Monitor a Linux Server with the Opsentry Agent

By the Opsentry team · June 25, 2026 · 8 min read

External checks tell you whether customers can reach your service. They can't tell you that the database host is at 97% memory, or that a disk has been quietly filling for three days. For that you need a view from inside the machine — and that's what the Opsentry agent gives you. This guide walks through installing the agent on a Linux server and setting up the checks that catch most real-world outages before they happen: CPU and load, memory, disk, PostgreSQL, and log patterns.

The whole setup takes about ten minutes. Everything is configured centrally in Opsentry; the agent simply pulls its check list and runs it on a schedule, so there's no config file to manage on the host itself.

Step 1 — Install the agent

In Opsentry, open Admin → Agents → Add agent. You'll get a unique agent token and a one-line install command. The agent is a single static Go binary with no runtime or dependencies — it runs the same on bare metal, a VM, or inside a container.

On the server, run the command shown in the dashboard (it embeds your token):

# Copy the exact command — with your token — from Admin → Agents
curl -fsSL https://get.opsentry.io/agent | sh

# Start the agent with the token from the dashboard
sudo opsentry-agent --token agt_********************

On first start the agent registers itself, then polls /api/agent/config on an interval (10 minutes by default) and begins running whatever checks you've configured. To keep it running across reboots, install it as a service — a minimal systemd unit is all you need:

# /etc/systemd/system/opsentry-agent.service
[Unit]
Description=Opsentry monitoring agent
After=network-online.target

[Service]
ExecStart=/usr/local/bin/opsentry-agent --token agt_********************
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now opsentry-agent

That's the only thing you ever do on the host. From here on, every check is added and tuned in Opsentry.

Step 2 — Watch CPU and load

Sustained high CPU or a load average above your core count is the classic "something is wrong" signal. In Admin → Agents, pick your host, add a CPU check, and set a threshold with headroom — alerting at 85% gives you time to react before the box is pinned. Each check is a small declarative config; the CPU one looks like this:

cpu:
  usage_percent: 85          # alert when sustained usage crosses 85%
  load_per_core: 1.5         # 1-min load average per core

interval: 60s
consecutive_failures: 3      # require 3 bad samples before alerting

The consecutive_failures setting matters: a single spike during a deploy or a GC pause is noise. Three samples in a row is signal. This is the simplest way to keep host monitoring trustworthy.

Step 3 — Watch memory and swap

Memory exhaustion is what summons the OOM killer, and it usually arrives with warning — a slow climb across deploys, or swap that starts thrashing. Add a Memory check:

memory:
  threshold_percent: 90
  swap_threshold_percent: 80

interval: 60s

Watch swap as well as RAM. A server that has started leaning on swap is already degraded even if free memory looks acceptable, and swap thrashing tanks latency long before anything goes hard-down.

Step 4 — Watch disk

A full disk takes down databases, logging, and the application all at once, and it's almost always avoidable — the disk crosses 80%, then 90%, then 98% over days. Add a Disk check per mount point you care about:

disk:
  path: "/"
  threshold_percent: 90

interval: 300s

If your database, logs, or uploads live on a separate volume, add a check for each path — a healthy root filesystem tells you nothing about a /var/lib/postgresql partition that's about to fill.

Step 5 — Watch your database

For a host running PostgreSQL, the agent can read internals no external probe can see — connection-pool saturation and replication lag chief among them. Add a PostgreSQL check pointed at the local instance:

postgresql:
  host: "127.0.0.1:5432"
  connection_usage_percent: 80   # of max_connections
  replication_lag_seconds: 30

interval: 60s

Connection saturation is one of the most common causes of "the app is up but every request times out," and it's invisible from the outside until it tips over. The agent ships the same style of check for MySQL, Redis, and MongoDB.

Step 6 — Scan logs for trouble

Some failures never move a system metric — they only show up as a flood of errors in a log file. A Log scan check watches a file for patterns and alerts when matches cross a rate:

logscan:
  path: "/var/log/app.log"
  patterns: ["(?i)error", "(?i)panic", "(?i)fatal"]
  max_matches: 10        # per interval before alerting

interval: 60s

Keep the patterns specific enough that a normal hour stays quiet. The goal is to catch a stack-trace storm the moment it starts, not to re-alert on a single benign warning you've already triaged.

How alerts and incidents work

When any check crosses its threshold for the required number of consecutive samples, the agent reports it and Opsentry opens an incident automatically — then notifies you by email, Slack, Microsoft Teams, Discord, Telegram, or webhook. This is the same incident pipeline, the same notification rules, and the same HTTP API as your external checks, so there's nothing new to learn and nowhere new to look. Agent results and external results land on one timeline.

The point of the agent is lead time. A disk crossing 85% at lunchtime is a ten-minute task that afternoon; the same disk at 100% at 2 a.m. is an outage. Same root cause, completely different day.

A sensible starting point

If you're setting up a new host, start with these five checks — CPU, memory, disk, your primary datastore, and a log scan of your application log. They cover the failure modes behind the large majority of host-level incidents. Add more specific checks (file descriptors, systemd unit status, certificate expiry, queue depth) as you learn what your particular workload likes to break on.

Don't drop your external checks

The agent is half the picture. It shares fate with the host it runs on: if the network partitions or DNS expires, the server is perfectly healthy and the agent happily reports green while every customer gets an error. Pair it with external checks that travel the same path your users do. For the reasoning behind running both, see Agent-Based vs External Monitoring: When You Need Both, and for tuning the external side, our guide to uptime monitoring best practices.