Skip to content
macOSDeep Dive Published Updated 4 min readViews unavailable

macOS Content Caching: Diagnose Capacity, Scope, and Parent Selection

Use Apple's cache utilities and metrics to distinguish an inactive Mac content cache from a cold workload, capacity pressure, or a parent-cache routing issue.

Apple Content Caching is a local service for supported Apple-delivered content, including shared content such as apps and software updates and, when enabled, personal iCloud data. It can reduce repeated downloads for a managed fleet, but it is not a general-purpose HTTP proxy or a guarantee that every update request will be served from a nearby Mac. A useful diagnosis separates service state, client scope, storage pressure, and actual bytes served.

Establish state before changing settings

Start with the read-oriented utility commands Apple documents:

AssetCacheManagerUtil canActivate
AssetCacheManagerUtil isActivated
AssetCacheManagerUtil settings
AssetCacheManagerUtil status

Apple notes that most AssetCacheManagerUtil actions require root privileges. The commands above are intended to inspect eligibility, activation, settings, and status; do not begin with flushCache, deactivate, or a settings reload as a generic repair step. Those commands change service or cache state and can remove data or interrupt clients.

For a bounded log sample, inspect the Content Caching subsystem rather than collecting the entire unified log:

log show --last 1h --predicate 'subsystem == "com.apple.AssetCache"'

Record the macOS version, cache host, time range, and exact command with the output. A status response is a point-in-time check; it does not prove that clients are discovering the server or that the cache is serving useful data.

Check scope and capacity separately

Read AssetCacheManagerUtil settings for the data path and configured limits. The documented CacheLimit value of 0 means no explicit cap, not that the volume has unlimited usable space. ReservedVolumeSpace preserves a minimum amount of free space for the volume, while AllowCacheDelete permits macOS to purge cached content when other applications need storage. Consider both the file-system free space and these policy values before moving a cache or changing its limit.

For macOS 13 and later, Apple places the user-facing controls in System Settings → General → Sharing → Content Caching. Apple documents System Preferences → Sharing for macOS 12.0.1 or earlier; verify the interface on intermediate macOS 12.x releases rather than assuming the same boundary. For managed fleets, use the supported device-management configuration rather than editing undocumented preference keys. If an administrator uses documented advanced keys, Apple says that some changes require a settings reload and others a stop/start; do not assume a reload applies every key.

The parent list also changes the interpretation of a healthy cache. Apple documents that unavailable parents are skipped and that, if all configured parents are unavailable, the cache falls back to downloading from or uploading to Apple directly. A cache that remains active while origin traffic rises may therefore be serving as a fallback rather than failing outright. Check parent reachability, selection policy, and the clients’ allowed listen ranges before changing the hierarchy.

Read the metrics as a time series

Activity Monitor’s Cache pane is the first supported view for a quick operational check. Apple stores detailed metrics under /Library/Application Support/Apple/AssetCache/Metrics; the metrics database remains there even if the content data path is moved. The documented database model is versioned and Apple warns that it may change, so avoid making a long-lived monitoring pipeline depend on private schema details without a compatibility plan.

For an interval with rows, compare the direction-specific byte counters:

  • bytesFromCacheToClient shows cache-served bytes reaching client devices.
  • bytesFromOriginToClient shows bytes downloaded from Apple and delivered to clients.
  • bytesFromParentToClient and bytesFromPeerToClient distinguish upstream cache paths.
  • requestsRejectedForNoSpace and the bytesPurged... fields help explain capacity pressure.

Apple’s metrics omit all-zero rows while the service is idle. No new row is therefore not equivalent to an error; correlate it with client requests and the reporting interval. Likewise, a low cache-served share can be a cold or changing workload rather than a broken daemon. Compare like-for-like periods, and use the cache-pressure and rejected-request indicators before increasing storage or disabling automatic deletion.

Change one variable at a time

If status is inactive, resolve activation eligibility and the configured sharing state first. If clients are not using the cache, verify that their subnets fall within the intended service scope and that routing or DNS discovery matches the deployment design. If origin bytes dominate, observe more than one update cycle before concluding the cache is ineffective. If rejected requests or recent purges rise, check actual free space, CacheLimit, ReservedVolumeSpace, and whether the data volume is healthy.

Only after preserving a baseline should you change cache limits, listen ranges, parent selection, or the storage path. Keep a rollback value and maintenance window. Flushing the cache is not a neutral diagnostic: it removes the very data that would otherwise answer repeat requests and can temporarily increase WAN use.

Related:

Sources:

Comments