The most common problem with iCloud Drive has been delayed syncing. Move or copy a file into iCloud Drive, and it simply doesn’t sync. Sometimes iCloud’s circular progress indicator starts off well, and may even reach the finish, but at some stage the upload gets stuck, sometimes for many hours. To help you diagnose problems, my free utility Cirrus contains a test that uploads a file to iCloud Drive. Following that, you can then check the log to see how that worked out. This article describes in broad terms what you should see in the log when this is performed in Sonoma, with its new FileProvider subsystem.

Cirrus performs the test as follows:

1. It first writes a 1 MB file containing 0x88 bytes as data to ~/Library/Preferences/co.eclecticlight.Cirrus.data
2. It then creates a URL to a new file co.eclecticlight.Cirrus.data in iCloud Drive, at the path ~/Library/Mobile Documents/com~apple~CloudDocs/co.eclecticlight.Cirrus.data
3. If that succeeds, it removes that new file and copies the 1 MB file from ~/Library/Preferences/co.eclecticlight.Cirrus.data into your iCloud Drive at ~/Library/Mobile Documents/com~apple~CloudDocs/co.eclecticlight.Cirrus.data

Before Sonoma

When I introduced this test four years ago, I wrote up my analysis of the log, in this article. There I identified three distinct phases:

1. the upload phase, in which CloudKit (blue) and cloudd (grey) work with MMCS (green) to upload the new item;
2. the sync up phase, in which the new file is created in iCloud Drive;
3. the sync down phase, in which the file details are sent back to your Mac and generate a stub file in your local iCloud Drive folder.

Eviction in Sonoma

Three months ago I built up the courage to take a first look at the changes brought in Sonoma 14.1.1, with its move to a FileProvider mechanism. In this article I started gently by looking at the process of eviction in a nonreplicated FileProvider, with Optimise Mac Storage turned on.

I found that traditional iCloud subsystems such as CloudDocs now play minimal roles, and the overwhelming majority of significant log entries are made by com.apple.FileProvider.

Cirrus’ test in Sonoma

To ensure that I captured all relevant log entries, immediately after I ran the file upload test in Cirrus I captured log excerpts for the traditional subsystems and processes using Cirrus, and for com.apple.FileProvider using Ulbow. These were obtained within minutes of completing the test, to ensure that ephemeral log entries that aren’t written to the Persist log store were still available. Leave log capture for any longer, and those entries will all have been removed from the log; for com.apple.FileProvider that loses the majority of its entries (although that can be altered by changing log preferences).

Overall, these confirm that CloudDocs now has little involvement in iCloud Drive transactions, while much of the action is recorded in FileProvider’s entries. Those are well-designed using Emoji, which makes them far more accessible: kudos to Johannes Fortmann and others in the Cloud File Providers team for some of the best log entries I’ve seen.

Uploading the test file using Cirrus occurred in three main phases:

• initial changes made to the File Server (FS) tree made primarily by CloudKit;
• an upload phase, in which the data content of the file was chunked by the venerable MMCS (MobileMe Chunking Service, whose origins date back 15-25 years), then uploaded by CloudKit and cloudd;
• further changes made to both File Server (FS) and File Provider (FP) trees processed by FileProvider with CloudKit handling database records, and cloudd working in a background session.

My test was run with a local Content Caching Server active, and cloudd noted that and dealt with that local server. Although bird isn’t mentioned in my diagram, it played a major role with vouchers and the persona for the iCloud accountID throughout.

In the diagram below, I annotate FileProvider sections using the same Emoji that appear in the log. References there to snapshots aren’t of course APFS volume snapshots, but those for the File Server and Provider.

As far as log entries are concerned, this whole process is started and ended by the FileProvider. While its stages before and immediately after the upload phase appear relatively succinct and purposeful, those following completion of uploading appear repetitive, and are far harder to understand or explain.

Finally, it’s clear from these log entries that iCloud Drive is subject to the same throttling that can be applied to CloudKit databases. In this case, no throttling was applied at any stage. However, throttling doesn’t appear to affect transfer of file data, as I’ll explain in the next article, where I look at the deletion of a file from iCloud Drive.

Further reading

API entry point
WWDC 2021 presentation
Dataless files