@obsrviq/system

The Obsrviq host agent — streams system metrics (CPU, memory, load, network, disk) from any Linux/macOS server to Obsrviq. Pure-JS, zero native dependencies (reads os built-ins, Linux /proc, and fs.statfs), so it installs with a plain npm i and never needs a compiler.

It is best-effort by design: it never throws into the host process, caps its own footprint, and re-queues samples across brief network outages.

Install & run as a service (Linux, systemd)

npm i -g @obsrviq/system
sudo obsrviq-system enable \
  --key sk_live_… \
  --label env=prod --label role=web

enable writes /etc/obsrviq/system.env + a hardened systemd unit (MemoryMax=128M, CPUQuota=20%) and starts it. Manage with systemctl status obsrviq-system, or obsrviq-system disable.

Run in the foreground (any OS)

OBSRVIQ_KEY=sk_live_… obsrviq-system run --interval 10

Embed in a Node process

import { start } from '@obsrviq/system';

const agent = start({ key: process.env.OBSRVIQ_KEY, intervalSeconds: 10, labels: { env: 'prod' } });
// later: await agent.stop();  // flushes once

Metrics

Sampled each interval and shipped to Obsrviq:

| Metric | Description | |---|---| | cpu | overall CPU utilisation, 0–100 % | | mem.used_pct | memory used, 0–100 % | | load1 | 1-minute load average | | disk.used_pct | root filesystem used, 0–100 % | | net.rx_bps · net.tx_bps | network throughput in / out, bytes/sec | | net.rx_pps · net.tx_pps | network packet rate in / out, packets/sec | | net.rx_bytes · net.tx_bytes | bytes since the last sample — summed over a window = total data transferred (in / out) | | net.rx_pkts · net.tx_pkts | packets since the last sample — summed = total packets (in / out) |

All net.* metrics are Linux-only (read from /proc/net/dev); CPU, memory, load, and disk work cross-platform.

Top processes under load (Linux)

When CPU crosses a threshold the agent captures a process snapshot — the top consumers by CPU and memory, like a frozen top from the moment it hurt — so you can see what pinned the box. It fires at cpu ≥ 50 % by default with a 120 s cooldown (so a sustained spike yields a few snapshots, not a flood). Command lines are captured with secret redaction (--password, --token, -p… are masked). Tune with --proc-threshold, --proc-cooldown, --proc-top; drop command lines with --no-cmdline or disable with --no-proc.

Request monitoring from access logs (Linux)

Point the agent at a web-server access log and it reports per-endpoint latency, throughput, and error rates — no code changes. It tails the log, normalises routes (/user/123 → /user/:id) to bound cardinality, and ships pre-aggregated p50/p95/p99 (mergeable DDSketch) plus status-class counts.

obsrviq-system enable --key sk_live_… \
  --log /var/log/nginx/access.log:nginx \
  --log /var/log/tomcat/access.log:ms

Each --log is path:format, where format names the units of the trailing latency value: nginx (decimal seconds, default), ms (integer ms), us (integer µs), or combined (no latency). Add a response-time field to your log once: nginx $request_time → :nginx; Tomcat AccessLogValve %D (ms) → :ms or %T (s) → :nginx; Apache %D (µs) → :us. Without a time field you still get throughput and status codes.

Configuration

| Flag | Env | Default | |---|---|---| | --key | OBSRVIQ_KEY | — (required) | | --endpoint | OBSRVIQ_ENDPOINT | Obsrviq ingest | | --interval | — | 10 (seconds) | | --label k=v | OBSRVIQ_LABELS (k=v,k=v) | none | | --log path:format | OBSRVIQ_LOGS (path:format,…) | none | | --proc-threshold | OBSRVIQ_PROC_THRESHOLD | 50 (% CPU) | | --proc-cooldown | OBSRVIQ_PROC_COOLDOWN | 120 (seconds) | | --proc-top | OBSRVIQ_PROC_TOP | 8 (processes) | | --no-cmdline | OBSRVIQ_NO_CMDLINE | capture (redacted) | | --no-proc | OBSRVIQ_NO_PROC | enabled |