FreeBSD Server Monitoring Guide

Why FreeBSD Monitoring is Different

FreeBSD ships with a robust set of monitoring tools in the base system. Unlike Linux distributions where you often need to install third-party packages just to see basic system metrics, FreeBSD gives you top, vmstat, systat, sockstat, and gstat out of the box. Before reaching for Prometheus or Grafana, learn what the base system provides. These built-in tools have zero dependencies, minimal overhead, and work over any SSH session -- making them indispensable for troubleshooting production incidents where installing new packages is not an option.

Built-in Monitoring: top

The top command on FreeBSD is more capable than many administrators realize. Run it with the -SHP flags for the most useful view:

top -SHP

The -S flag includes system processes, -H shows individual threads rather than just processes, and -P displays per-CPU usage breakdowns. This combination reveals exactly which threads are consuming CPU time and how load distributes across cores. The header section shows swap usage, interrupt rates, and CPU states broken down into user, nice, system, interrupt, and idle percentages. Press m while running to sort by memory usage, or P to sort by CPU. On FreeBSD, top also displays the ARC (Adaptive Replacement Cache) size used by ZFS, which is critical for understanding memory allocation on ZFS-backed systems.

Built-in Monitoring: vmstat

For a real-time system overview without the overhead of a full-screen interface, vmstat is the go-to tool:

vmstat -w 2

The -w flag sets the interval in seconds. The output columns are organized into groups: procs (r = runnable, b = blocked, w = swapped), memory (active, inactive, wired, free), page (faults, re-attached, pi = paged in, po = paged out), disk (operations per device), faults (interrupts, system calls, context switches), and cpu (user, system, idle). The key indicators to watch are the pi and po columns -- if you see sustained non-zero values in paged-out (po), the system is under memory pressure and actively swapping. On a healthy FreeBSD server, po should be zero during normal operations.

Built-in Monitoring: systat

The systat utility is a curses-based, interactive monitoring tool that is unique to BSD systems. It provides several display modes, each tailored to a specific subsystem:

systat -ifstat 2    # Network throughput per interface
systat -vmstat 2    # System overview (CPU, memory, disks)
systat -iostat 2    # Disk I/O statistics per device

The -ifstat mode is particularly valuable for monitoring network throughput in real time -- it shows bytes in and bytes out per interface, updated at the interval you specify. The -vmstat mode provides a comprehensive dashboard of CPU states, memory usage, disk activity, and interrupt rates all in a single view. The -iostat mode breaks down disk operations by device, showing reads, writes, and queue depth. Because systat runs in the terminal, it works perfectly over SSH sessions to remote servers without needing X11 forwarding or a web browser.

Built-in Monitoring: sockstat

To verify which services are listening on which ports, sockstat is the FreeBSD equivalent of checking network bindings:

sockstat -4l    # Show IPv4 listening sockets
sockstat -c     # Show connected sockets
sockstat -6l    # Show IPv6 listening sockets

The -4l flags filter for IPv4 listening sockets, showing you the user, process name, PID, protocol, and local address for every bound port. This is essential after deploying a new service -- you can immediately confirm it is bound to the correct address and port. The -c flag shows established connections, which is useful for verifying that clients are connecting and for counting active connections to services like Nginx or MySQL. Combine with grep to filter for specific services: sockstat -4l | grep nginx.

ZFS Monitoring: gstat and zpool

On FreeBSD systems using ZFS, disk monitoring requires ZFS-aware tools. The gstat utility provides real-time I/O statistics per GEOM device:

gstat -a                  # I/O stats for all devices
zpool status              # Pool health and resilver progress
zpool iostat -v 2         # ZFS I/O stats per vdev, every 2 seconds
zfs list -o name,used,avail,refer

The gstat -a command shows operations per second, throughput, and busy percentage for every disk device, including individual disks within a ZFS mirror or RAIDZ. Run zpool status regularly to check for degraded pools, faulted devices, or ongoing resilver operations. The zpool iostat -v 2 command is especially valuable because it breaks down I/O at the vdev level, showing you exactly which disks in a pool are handling the most reads and writes. For capacity planning, zfs list with the -o flag gives you a clean view of used space, available space, and referenced data for every dataset and snapshot.

Adding Prometheus + Node Exporter

Once you have mastered the built-in tools for interactive troubleshooting, the next step is long-term metrics collection. Prometheus with Node Exporter provides historical data, trend analysis, and alerting. Install on FreeBSD using pkg:

pkg install node_exporter

# Enable in /etc/rc.conf
sysrc node_exporter_enable="YES"

# Start the service
service node_exporter start

Node Exporter runs on port 9100 by default and exposes system metrics in Prometheus format. The FreeBSD version of Node Exporter includes platform-specific collectors that are not available on Linux: the ZFS collector exposes pool health, ARC hit rates, and dataset usage, while the devstat collector provides disk I/O metrics from the FreeBSD kernel. Verify it is running with sockstat -4l | grep 9100, then configure your Prometheus server to scrape it by adding the target to your prometheus.yml scrape configuration.

Grafana Setup on FreeBSD

Grafana turns your Prometheus data into dashboards and visualizations. Install and enable it the FreeBSD way:

pkg install grafana

# Enable in /etc/rc.conf
sysrc grafana_enable="YES"

# Start the service
service grafana start

Grafana runs on port 3000 by default. The configuration file lives at /usr/local/etc/grafana/grafana.ini -- not in /etc like on Linux. After logging in with the default credentials (admin/admin), add Prometheus as a data source pointing to http://localhost:9090. Import community dashboard #1860 (Node Exporter Full) for a comprehensive view of system metrics. For FreeBSD-specific panels, create custom dashboards that query ZFS ARC statistics (node_zfs_arc_hits, node_zfs_arc_misses) and pool capacity metrics that the FreeBSD collectors expose.

Alerting Essentials

Collecting metrics is only useful if you act on them. Set up Prometheus alerting rules tailored to FreeBSD systems. Create an alert rules file and reference it in your prometheus.yml:

# /usr/local/etc/prometheus/rules/freebsd.yml
groups:
  - name: freebsd
    rules:
      - alert: ZFSPoolDegraded
        expr: node_zfs_zpool_state{state!="online"} > 0
        for: 5m
        annotations:
          summary: "ZFS pool is degraded"

      - alert: DiskSpaceOver85
        expr: (node_filesystem_size_bytes - node_filesystem_avail_bytes)
              / node_filesystem_size_bytes > 0.85
        for: 10m
        annotations:
          summary: "Disk usage above 85%"

      - alert: HighCPU
        expr: 100 - (avg by(instance)(rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 90
        for: 15m
        annotations:
          summary: "CPU usage above 90% for 15 minutes"

      - alert: MemoryPressure
        expr: node_memory_free_bytes / (node_memory_free_bytes
              + node_memory_active_bytes + node_memory_inactive_bytes
              + node_memory_wired_bytes) < 0.05
        for: 10m
        annotations:
          summary: "Free memory below 5%"

These rules cover the critical areas for FreeBSD servers: ZFS pool health degradation, disk capacity thresholds, sustained high CPU usage, and memory pressure. The ZFS pool alert is particularly important because a degraded pool means a disk has failed and the array is running without redundancy. Connect Prometheus Alertmanager to your notification channels -- email, Slack, or PagerDuty -- to ensure the right people are notified when thresholds are breached.

Learn about our monitoring and NOC services