NAME

footprint — gathers memory information about one or more processes

SYNOPSIS

footprint --sample interval ...

footprint -h, --help

DESCRIPTION

The footprint utility gathers and displays memory consumption information for the specified processes or memory graph files.

footprint will display all addressable memory used by the specified processes, but it emphasizes memory considered 'dirty' by the kernel for purposes of accounting. If multiple processes are specified, footprint will de-duplicate multiply mapped objects and will display shared objects separately from private ones.

footprint must be run as root when inspecting processes that are not owned by the current user.

Processes are specified using a PID, exact process name, or partial process name. Memory information will be displayed for all processes matching any provided name.

OPTIONS

-a, --all: target all processes (will take much longer)
-j, --json path: also save a JSON representation of the data to the specified path
-f, --format bytes|formatted|pages: textual output should be formatted in bytes, pages, or human-readable formatted (default)
--sort column: textual output should be sorted by the given column name, for example dirty (default), clean, category, etc.
-p, --proc name: target the given process by name (can be used multiple times)
-p, --pid pid: target the given process by pid (can be used multiple times)
-x, --exclude name/pid: exclude the given process by name or pid (can be used multiple times)
often used with --all to exclude some processes from analysis
-t, --targetChildren: in addition to the supplied processes, target their children, grandchildren, etc.
-s, --skip: skip processes that are dirty tracked and have no outstanding XPC transactions (i.e., are "clean")
--minFootprint MiB: skip processes with footprint less than the provided minimum MiB.
--forkCorpse: analyze a forked corpse of the target process rather than the original process. Due to system resource limits on corpses this argument is not compatible with --all or if attempting to analyze more than a couple processes.
-v: display all regions and vmmap-like output of address space layout.
Without this flag the default output is a summary of the totals for each memory category.
-w, --wide: show wide output with all columns and full paths (implies --swapped --wired)
--swapped: show swapped/compressed column
--wired: show wired memory column
--vmObjectDirty: interpret dirty memory as viewed by VM objects in the kernel, rather than the default behavior which interprets dirty memory through the pmap. This mode may calculate a total footprint that does not match what is shown in other tools such as top(1) or Activity Monitor.app. However, it can provide insight into dirty memory that is by design not included in the default mode, such as dirty file-backed memory or a VM region mapped into a process that is normally accounted to only the process that created it.
The --vmObjectDirty mode was the default in versions prior to macOS 10.15.
--unmapped: search all processes for memory owned by the target processes but not mapped into their address spaces (see the discussion in MEMORY ACCOUNTING for more details)
--sample interval: Start footprint in sampling mode, gathering data every interval seconds (which can be fractional like 0.5). Text output will be a concatenation of usual text output with added timestamps. JSON output will contain a "samples" array with many of the same key/values that would normally be at the top level. All other command line options are also supported in sampling mode.
--sample-duration duration: Time limit on the number of seconds to sample when combined with --sample. When this flag is omitted or set to 0, sampling continues until <ctrl-c>.
-h, --help: display help and exit

COLUMNS

Column names between parentheses indicate that they are a subset of one or more non-parenthesized columns.

Dirty: Memory that has been written to by a process, which includes "Swapped", purgeable non-volatile memory, and implicitly written memory such as zero-filled. A process's footprint is equal to the total of all dirty memory.
(Swapped): A subset of "Dirty" memory that has been compressed or swapped out by the kernel.
Clean: Resident memory which is neither "Dirty" nor "Reclaimable".
Reclaimable: Resident memory that has been explicitly marked as available for reuse. Memory can be marked reclaimable when it is made purgeable volatile (including purgeable empty) or by using madvise(2) with advice such as MADV_FREE. Reclaimable memory can be taken away from a process at any time in response to system memory pressure.
(Wired): Memory that has been wired down (e.g., by calling mlock(2) ). This memory is usually a subset of "Dirty" and cannot be paged out.
Regions: The count of VM regions contributing to this entry. Each binary segment contained within the shared cache region is considered a separate region for display purposes.
Category: A descriptive name for this entry, such as a human-readable name for a VM_MEMORY_* tag, a path to a mapped file, or a segment of a loaded binary.

INVESTIGATING MEMORY FOOTPRINT

footprint provides an efficient calculation of a process's memory footprint and a high-level overview of the various categories of memory contributing to that footprint. The details that it provides can be used as a starting point in an investigation.

Prioritize reducing "Dirty" memory. Dirty memory cannot be automatically reclaimed by the kernel and is directly used by various parts of the OS as a measure of a process's contribution to system memory pressure.
Next, focus on reducing "Reclaimable" memory, especially purgeable volatile memory which will become dirty when marked non-volatile. Although this memory can be cheaply reclaimed by the kernel, purgeable volatile memory is commonly used as a cache of data that may be expensive for a user process to recreate (such as decoded image data).
"Clean" memory can also be cheaply taken by the kernel, but unlike "Reclaimable" it can be restored automatically by the kernel without the help of a user process. For example, clean file backed data can be automatically evicted from memory and re-read from disk on-demand. Having too much clean memory can still be a performance problem, since large working sets can cause thrashing when loading and unloading various parts of a process under low memory situations.
Lastly, avoid using "Wired" memory as much as possible since it cannot be paged out or reclaimed.

Malloc memory: Memory allocated by malloc(3) is one of the most common forms of memory, making up what is usually referred to as the 'heap'. This memory will have a category prefixed with 'MALLOC_'. malloc(3) allocates VM regions on a process's behalf; the contents of those regions will be the individual allocations representing objects and data in a process. Refer to the heap(1) tool to further categorize the objects contained within a malloc memory region, or leaks(1) to detect a subset of heap memory that is no longer reachable.
Binary segments: Loaded binaries will be visible as an entry with both the segment type and the path to the binary, most often __TEXT, __DATA, or __LINKEDIT segments. Non-shared cache binaries and pages in the __DATA segment (such as those that contain modified global variables) can often have dirty memory.
Mapped files: File-backed memory allocated using mmap(2) will show up as 'mapped file' along with the path to the file.
VM allocations: Most other types of memory can be tagged with a name that indicates what subsystem allocated the region (see mmap(2) for more information). For instance, Foundation.framework may allocate memory and tag it with VM_MEMORY_FOUNDATION, which appears in footprint's output as 'Foundation'. Processes are able to allocate memory with their own tags by using an appropriate tag in the range VM_MEMORY_APPLICATION_SPECIFIC_1-VM_MEMORY_APPLICATION_SPECIFIC_16. Memory which does not fall into one of the previous categories and has not been explicitly tagged will be marked 'untagged (VM_ALLOCATE)'.
Kernel memory: In the special case of analyzing kernel_task, footprint's output and categories will mirror much of the data also available via zprint(1). This is memory allocated by the kernel or a kernel extension and is generally unavailable to userspace directly. Despite the restricted access, userspace programs often influence when and how much memory the kernel allocates (e.g., for resources allocated on behalf of a user process).

For malloc and VM allocated memory, details about when and where the memory was allocated can often be obtained by enabling MallocStackLogging and using malloc_history(1) to view the backtrace at the time of each allocation. Xcode.app and Instruments.app also provide visual tools for debugging memory, such as the Xcode's Memory Graph Debugger.

vmmap(1) provides a similar view to footprint, but with an emphasis on displaying the raw metrics returned by the kernel rather than the simplified and more processed view of footprint. One important difference is that vmmap(1)'s "DIRTY" column does not include the compressed or swapped memory found in the "SWAPPED" column. Additionally, vmmap(1) can only operate on a single process and contains additional information such as a malloc zone summary.

MEMORY ACCOUNTING

Determining what dirty memory should and should not be accounted to a process is a difficult problem. Memory can be shared by many processes, it can sometimes be allocated on your behalf by other processes, and no matter how the accounting is done can often be expensive to accurately calculate.

Many operating systems have historically exposed memory metrics such as Virtual Size (VSIZE) and Resident Size (RSIZE/RPRVT/RSS/etc.). Metrics such as these, which are useful in their own respect, are not great indicators of the amount of physical memory required by a process to run (and therefore the memory pressure that a process applies to the system). For instance, Virtual Size includes allocations that may not be backed by physical memory, and Resident Size includes clean and volatile purgeable memory that can be reclaimed by the kernel (as described earlier).
On the other hand, analyzing the dirty memory reported by the underlying VM objects mapped into a process (the approach taken by --vmObjectDirty), while more accurate, is expensive and cannot be done in real-time for systems that need to frequently know the memory footprint of a process.

Apple platforms instead keep track of the 'physical footprint' by using a per-process ledger in the kernel that is kept up-to-date by the pmap and other subsystems. This ledger is cheap to query, suitably accurate, and provides additional features such as tracking peak memory and the ability to charge one process for memory that is no longer mapped into it or that may have been allocated by another process. In cases where footprint is unable to analyze a portion of 'physical footprint' that is not mapped into a process, this memory will be listed as 'Owned physical footprint (unmapped)'. If this memory is mapped into another userspace process then the --unmapped argument can be used to search all processes for a mapping of the same VM object, which if found will provide a better description and what process(s) have mapped the memory. This also happens by default when targeting all processes via --all. Any memory still listed as "(unmapped)" after using --unmapped is likely not mapped into any userspace process and instead only referenced by the kernel or drivers.
The exact definition of this 'physical footprint' ledger is complicated and subject to change, but suffice it to say that the default mode of footprint aims to present an accurate memory breakdown that matches the value reported by the ledger. Most other diagnostic tools, such as the 'MEM' column in top(1), the 'Memory' column in Activity Monitor.app, and the Memory Debug Gauge in Xcode.app, query this ledger to populate their metrics.

Physical footprint can be potentially be split into multiple subcategories, such as network related memory, graphics, etc. When a memory allocation (either directly mapped into a process, or owned but unmapped) has such a classification, footprint will append it to the category name such as 'IOKit (graphics)' or 'Owned physical footprint (unmapped) (media)'.