Server agent

Install one agent and your server streams CPU, memory, disk, network, processes, Docker containers and logs to Perch — continuously, with nothing to open on your firewall.

The agent is the official OpenTelemetry Collector (contrib) with a Perch configuration. It only makes outbound HTTPS requests to Perch; Perch never connects to your server.

Install in 3 steps

Step 1 of 3
Create an install key
Open Settings → Agent keys (admins only) and create a key. One key works on all your servers — copy it, it is shown only once.
Step 2 of 3
Run the install command on each server
Replace YOUR_INSTALL_KEY with your key, or use Add a server, which fills it in for you.
Loading commands…
Step 3 of 3
See the server in Perch
Within a minute it appears under Servers, named after its hostname, and shows online while data arrives.

What you get

Where	What
Server page	Charts for CPU (total, by state, per core), memory, disks, disk I/O, network and load over 1 hour to 30 days, plus top processes, containers and Redis.
Logs	Search every server’s logs: words, minimum severity, server, file, service or container — with live tail.
Alert rules	Get notified when CPU, memory, disk or load crosses a limit, or when matching log lines pile up (or stop).
Servers	Every server at a glance: status, CPU / memory / disk, OS, agent version, last data.

What is collected

Data	Details	Every
CPU	Utilization by state, load average (1 / 5 / 15 min)	30 s
Memory & swap	Usage and utilization by state, paging	30 s
Disks	Usage per filesystem, disk I/O and operations	30 s
Network	Traffic, packets, errors and connections per interface	30 s
Processes	Process counts; CPU and memory of the top processes (command lines are never stored)	60 s
Docker (with --docker)	CPU, memory, network and I/O per container, plus container logs	30 s
Redis / Valkey (found automatically)	Memory vs maxmemory, clients, ops/sec, hit ratio, evictions, keys per database, last save, role — for every Redis running on the server	30 s
System logs	/var/log/syslog or /var/log/messages, /var/log/.log and /var/log//*.log (nginx, apache, mysql …) — or the systemd journal on systems without syslog files	live
App logs (found automatically)	The log folders of the apps on the server, grouped by project — see App logs below	live

App logs

On a server running several projects, the installer finds each app's log folder and ships it too — no paths to type. Perch groups the lines by project, named after the app folder, so you can filter the logs explorer to one project and follow it live.

Where it looks	Project name
`~/apps/APP/…/log, logs, storage/logs`	APP — Capistrano-style current/ and shared/log are followed across deploys
`~/APP/log`	APP
`/var/www/APP/…, /srv/APP/…, /opt/APP/…`	APP — Laravel storage/logs included
`~/.pm2/logs/APP-out.log`	APP (PM2)
Any *.log file a running program has open	its app folder
`/var/log/nginx/…`	nginx (the folder name); files directly in /var/log are “system”
`--log-path='/data/x/*.log'`	Extra paths you add at install (repeat the option; it replaces the saved list)

Step 1 of 3
See what would be collected
Before installing, or any time: the Find app logs command in step 2 above lists the folders, grouped by project, and changes nothing.
Step 2 of 3
Install (or run the install command again on an existing server)
The installer gives the agent user read-only access to those folders (ACLs — traverse-only on the folders above them), and a daily timer picks up projects deployed later. To pick one up now: sudo sh /opt/perch-agent/discover-logs.sh
Step 3 of 3
Choose what to keep
The server page lists every project and file with its volume. Switch off a noisy project or file — its lines are dropped as they arrive and don't count toward the daily quota. APM agents' own logs (newrelic_agent.log, scout_apm.log) are skipped.

Multi-line entries — Ruby, Python, Java, Node and PHP stack traces — arrive as one log entry with the error line they belong to. Uninstalling takes back the read access the installer gave.

Redis

The installer looks for redis-server / valkey-server processes listening on the machine and tracks each one — no flag needed. It reads the password from the Redis config file (requirepass in /etc/redis/redis.conf and similar) and stores it only in /etc/perch-agent/env (readable by root); it never reaches Perch. The agent reads Redis over its local address every 30 seconds.


Status	OK, Warning (memory ≥ 80 % of maxmemory — or of the server RAM when there is no limit —, evicted keys or rejected connections in the last 15 min) or Down (no answer for 3 minutes).
Alerts	Rule presets: Redis not responding, Redis memory %, evicted keys, connected clients.
Installed Redis later?	Run the install command again — it picks it up. --no-redis skips Redis.
Password not in a config file	The installer warns. Add `PERCH_REDIS_1_PASSWORD="…"` to `/etc/perch-agent/env`, then `systemctl restart perch-agent`.

Redis in a container, or on another machine? The health-endpoint integration files report the Redis your app uses (REDIS_URL) — see Health endpoint.

Status and alerts

Each server is a monitor in your organization: it shows online while data arrives and goes offline — opening an incident and notifying the alert channels you attach — when nothing arrives for 3 minutes.

For thresholds, create an alert rule (or use Create alert on the server page): for example CPU above 90 % for 5 minutes, disk above 85 %, or more than 10 ERROR lines containing “payment” in 15 minutes. Rules are checked every minute, for one server or all of them.

Data retention and limits

	Default
Metrics history	30 days
Logs	7 days
Log volume per server	500 MB per day — extra lines are dropped until midnight UTC and the server page shows a notice

Security

Install keys are stored hashed and shown once. Revoking a key under Agent keys stops every server using it immediately.

The agent runs as its own perch-agent system user with read access to logs (adm, systemd-journal groups). --docker also adds it to the docker group, which is equivalent to root — only use it where you need container data.

Troubleshooting

Problem	Check
Server never appears	`systemctl status perch-agent` and `journalctl -u perch-agent -f` — look for 401 (wrong or revoked key) or connection errors to Perch.
No logs from /var/log/messages	On some distributions that file is readable by root only. The agent reads the journal when no syslog file exists.
An app’s logs are missing	Run `sudo sh /opt/perch-agent/discover-logs.sh` — it lists the folders it collects and any it couldn't open (install the `acl` package if it says so). Logs elsewhere? Re-run the install command with `--log-path='/path/*.log'`. Files appear on the server page once they write a line.
Deleted a server, but its agent still runs	Its data is refused and the agent logs why. Uninstall the agent — or, to add the server back, unblock it under Settings → Agent keys.
Not Linux	Use the Docker command, or follow the OpenTelemetry Collector docs with the config URL from the Docker command.

Health endpoint →All integrations →