The only diagnostic tool for iCloud problems which is bundled with macOS seems to be the brctl command. Specifically,
brctl diagnose
which takes a while to dump a hefty .tgz archive containing what Apple describes as the clouddump “diagnosis” and logs. On a lightly-used MacBook Air running High Sierra 10.13.4, that output came to 94 MB, and decompressed to more than 260 MB.

This article describes what is in a clouddump folder, and what help it might be to someone struggling with iCloud problems.

Altogether, a clouddump provides over 120 items, and you’ll be pleased to know that I am not going to step through them individually. They break down into the following groups of files:

• brctl-dump.txt, which is a log of the process containing additional information,
• containers, a folder containing property lists for all iCloud-enabled app containers, such as iCloud.com.filemaker.plist, and a separate brctl-container-list.txt,
• db, a folder containing client and server databases,
• disk usage statistics and ls listings for iCloud’s caches (from CloudKit and bird) and ~/Library/Mobile Documents folders,
• ls listings for ~/Library/Application Support/CloudDocs and synced ~/Library/Mobile Documents folders,
• a folder full of various diagnostic and performance samples, such as memory leaks and allocation (malloc) history,
• lists of known extensions for packages and shared packages,
• a spindump performance profile of the whole system,
• a syslog copy, now largely useless because of the unified log,
• a logarchive taken from the unified log, here amounting to 240 MB,
• several other text listings about internals such as bird.

Currently, my tool Cirrus only opens the live log. I will shortly provide an option to access such logarchives for anyone wishing to use a clouddump.

Several of these reports overlap with the output produced by sysdiagnose, and there is an option to brctl to exclude material which is already included in sysdiagnose, to avoid duplication when that is also being performed.

Unless you are skilled at reading the unified log and accustomed to interpreting spindumps, the great majority of the files generated in a clouddump are going to be of little use to you. Indeed, as with sysdiagnose, the sheer quantity of information overwhelms, and it may appear difficult to know where to start.

I suspect that, as with sysdiagnose reports, Apple has in-house diagnostic tools for the analysis of clouddumps. Without those, trudging through these files would take a very long time, and we would emerge only too aware of how little we understand about iCloud.

There is one file which does contain some valuable tidbits without bringing that feeling of welling panic: brctl-dump.txt. Its highlights include:

• in server_state, last-sync gives the datestamp of the last iCloud sync, and that for shared databases;
• in client_state, syncUpBudget gives values in minutes, hours, and days for what is termed BRCSyncBudgetThrottle;
• devices lists all those devices known to be connected to this iCloud account, which is rather fuller than the listing given in iOS;
• in users, system, a size is given for ‘evictable’, i.e. those items in local storage which could be ‘put back’ into iCloud;
• in global sync up budget, the available budget is given in minutes, hours, and seconds, and as percentages;
• there are detailed usage listings by container (app), which includes all items in iCloud Drive. Although these entries are not easy to interpret, and not formatted to help, they give an idea of iCloud usage for each app or purpose.

BRCSyncBudgetThrottle and sync budgets provide more general insights into how iCloud operates, and implies that heavy users with limited budgets (presumably those using only the 5 GB free iCloud storage) may find its performance ‘throttled’ at times. This is a topic which Apple doesn’t appear to have detailed anywhere, but clearly of great interest if you are suffering performance problems.