One of the only ways to discover what’s going on with APFS is to browse the log. Compared to most other processes and subsystems, its entries are brief, to the point, and worth reading closely. This article provides a guide to help you identify and understand log entries made by APFS in recent versions of macOS, particularly Ventura and Sonoma.

You’ll find log entries from APFS with the following key fields:

• processImagePath kernel
• senderImagePath apfs
• eventMessage, such as apfs_vfsop_unmount:3580: all done. going home. (numMountedAPFSVolumes 55)

There is no APFS sub-system used in log entries.

Predicates and reading

To obtain APFS entries, use a predicate of
senderImagePath CONTAINS[c] "apfs"

Relevant information is also contained in related entries obtained with the following predicate terms:
subsystem CONTAINS[c] "com.apple.diskmanagement"
subsystem CONTAINS[c] "com.apple.mobileaccessoryupdater"
subsystem CONTAINS[c] "com.apple.DiskArbitration.diskarbitrationd"
senderImagePath CONTAINS[c] "IOAccessoryManager"
These are readily available in custom log excerpts in Mints.

The message field of each log entry made by APFS has a standard structure:

• The descriptive name of the APFS task, which might refer to a code procedure, e.g. nx_get_volume_group. Note that names prefixed with nx normally refer to the container layer, in accordance with the structures listed in the APFS Reference, although the j prefix isn’t used for the volume layer in the log.
• The task-specific identity number, e.g. 8051 for nx_get_volume_group. Some tasks can have more than one ID, and numbers may change with different versions of APFS.
• A description of the activity and any results.

Log entries by ID numbers

The following identity numbers appear well-used in recent versions of macOS. Listed in approximate numeric order they include:

• Space Manager metazone initialisation, spaceman_metazone_init: 110, 171, 600
• rename snapshot for removal, fs_insert_snapshot_metadata: 249
• crypto, block info, dev_init: 296
• device_handle block details, dev_init: 299
• container probe and check, nx_checkpoint_find_valid_checkpoint: 556, 560, 565
• crypto buffer allocation, cryptoAlloc: 650
• adds fresh mounted snapshot, nx_volume_group_update: 704
• mount volume info, handle_mount: 725
• mount volume set block size, handle_mount: 738
• handle snapshot mount, handle_mount: 817
• snapshot mount, handle_snapshot_mount: 996, 1144
• volume unmounting, stop background work, apfs_stop_bg_work: 831
• deleting snapshot, apfs_snap_vnop_remove: 1052, 1107
• initialise cache for mount, nx_mount: 1219, 1224
• transfer statistics, tx_flush: 1241
• adjust copy-on-write exempt count, apfs_update_cow_exempt_file_count: 1310
• object map cleanup, omap_cleanup: 1544
• container checkpoint search, nx_mount: 1548, 1550, 1553, 1575, 1580
• snapshot deletion, cleanup_snapshot_purgatory: 1805, 1808, 1826
• vnode_close() for container unload, container_unload: 1884
• unmount volume, apfs_log_mount_unmount: 1980
• initialise volume keybag, apfs_keybag_init: 2651
• snapshot merges, delete_clone_fs: 2778, 2915
• wait for purgatory cleaner to finish, apfs_vfsop_unmount: 2915
• volume name, apfs_log_op_with_proc: 3091
• unmount completion, apfs_vfsop_unmount: 3244, 3257
• Space Manager trim operations, spaceman_scan_free_blocks: 3293, 3295, 3303, 3306, 3311
• unwrap volume key, apfs_keybag_unlock_record_tag: 3322
• unwrap volume key, apfs_keybag_unlock_record: 3403
• snapshot deletion, apfs_vfsop_unmount: 3501, 3567, 3580
• bitmap update, gbitmap_update_thread_terminate: 6110
• anything to recover, er_state_obj_get_for_recovery: 7556, 7575
• volume name and group role, nx_volume_group_update: 7895
• buffer I/O only not raw disk access, bufatr_get_apfs: 8040
• volume group tree, nx_get_volume_group: 8051
• no-effaceable-storage, effaceable_is_disabled: 10727
• purge files, handle_purge_files: 10874
• print_unknown_ioctl: 18120
• unwrap metadata crypto state, apfs_mount: 28950
• file system won’t be encrypted, apfs_newfs: 30416

Log entry types listed by theme

Containers:

• container probe and check, nx_checkpoint_find_valid_checkpoint: 556, 560, 565
• initialise cache for mount, nx_mount: 1219, 1224
• container checkpoint search, nx_mount: 1548, 1550, 1553, 1575, 1580
• vnode_close() for container unload, container_unload: 1884
• volume name and group role, nx_volume_group_update: 7895
• volume group tree, nx_get_volume_group: 8051

Volumes:

• mount volume info, handle_mount: 725
• mount volume set block size, handle_mount: 738
• volume unmounting, stop background work, apfs_stop_bg_work: 831
• unmount volume, apfs_log_mount_unmount: 1980
• wait for purgatory cleaner to finish, apfs_vfsop_unmount: 2915
• volume name, apfs_log_op_with_proc: 3091
• unmount completion, apfs_vfsop_unmount: 3244, 3257
• buffer I/O only not raw disk access, bufatr_get_apfs: 8040

Snapshots:

• rename snapshot for removal, fs_insert_snapshot_metadata: 249
• adds fresh mounted snapshot, nx_volume_group_update: 704
• handle snapshot mount, handle_mount: 817
• snapshot mount, handle_snapshot_mount: 996, 1144
• deleting snapshot, apfs_snap_vnop_remove: 1052, 1107
• snapshot deletion, cleanup_snapshot_purgatory: 1805, 1808, 1826
• snapshot merges, delete_clone_fs: 2778, 2915
• snapshot deletion, apfs_vfsop_unmount: 3501, 3567, 3580

Space Manager:

• Space Manager metazone initialisation, spaceman_metazone_init: 110, 171, 600
• Space Manager trim operations, spaceman_scan_free_blocks: 3293, 3295, 3303, 3306, 3311

Encryption:

• crypto, block info, dev_init: 296
• crypto buffer allocation, cryptoAlloc: 650
• initialise volume keybag, apfs_keybag_init: 2651
• unwrap volume key, apfs_keybag_unlock_record_tag: 3322
• unwrap volume key, apfs_keybag_unlock_record: 3403
• no-effaceable-storage, effaceable_is_disabled: 10727
• unwrap metadata crypto state, apfs_mount: 28950
• file system won’t be encrypted, apfs_newfs: 30416

Example log sequences

Mounting a plain SSD formatted with a single APFS container and unencrypted volume.

Mounting a single APFS (Encrypted) volume on an external Thunderbolt 3 SSD.

Mounting a snapshot on a Time Machine backup store on an external disk.

Performing a clean unmount of an APFS volume.

Articles in this series

1. Files and clones
2. Directories and names
3. Containers and volumes
4. Snapshots
5. Encryption and sealing
6. Special file types
7. Command tools
8. Beyond, to vfs and volfs

References

Apple’s APFS Reference (PDF), last revised 22 June 2020.