fs_usage - macOS

Overview

fs_usage is a monitoring tool specific to macOS that reports on file system activity in real-time. It primarily tracks system calls and page faults involving file system activity, making it a powerful utility for diagnosing problems related to file access and usage. The command is especially useful for developers, system administrators, and power users who need to understand how applications interact with the file system.

Syntax

The basic syntax of the fs_usage command is as follows:

fs_usage [options] [filter1 [filter2 ...]]
  • options: Modifiers which change the behavior of the command.
  • filter: Filtering the output based on process names, process IDs, or other criteria.

Options/Flags

Below are some of the commonly used options and flags for fs_usage:

  • -f mode: Specifies the mode of reporting. Possible modes include network, filesys (default), cachehit, etc.
  • -w: Wider output. This option formats the output suitable for wider terminals.
  • -e: Exclude non-file system-related activities.
  • -F: Enable/disable full path reporting.
  • -i interval: Sampling interval in milliseconds. The default is the minimal sampling interval supported by the system.
  • -b: Batch mode, which can be more efficient and delay the output until there is a reasonable amount to process.

Examples

  • Basic Usage
    Monitor all file system activities:

    sudo fs_usage

  • Filter by Application
    Monitor file system usage by a specific application (e.g., Safari):

    sudo fs_usage Safari

  • Use with Interval
    Monitor with a custom interval of 500 milliseconds:

    sudo fs_usage -i 500

  • Network Activity Only
    Focus on network-related file system activity:

    sudo fs_usage -f network

Common Issues

  • Performance Impact: Continuous usage of fs_usage can significantly impact system performance. Use it for short monitoring sessions.
  • Permission Denied: fs_usage requires root privileges. Always use sudo to avoid access issues.

Integration

fs_usage can be used in conjunction with grep to filter output. For instance, to monitor all read and write operations by a process:

sudo fs_usage | grep -E "read|write"

For scripting or capturing long outputs, you might redirect the output to a file for later analysis:

sudo fs_usage -w > fs_usage_output.txt
  • iotop: Monitor I/O usage by macOS processes in a manner similar to top.
  • top: Display running processes along with various system info.
  • lsof: List open files belonging to active processes.

For additional documentation, visit the official Apple Developer documentation.