Content caching metrics on Mac

Overview

Multiple metrics are available to help you verify the status, health, and utilization of your content caches to optimize their usage in your deployment:

Declarative status items your device management service can subscribe to provide information about status and health.
Metrics report sent to an arbitrary HTTPS endpoint provide insights into volume and throughput.
Usage metrics available locally on a content cache provide fine-grained history data.
Basic statistics are visible in the Caches tab of Activity Monitor.

To determine if a different hardware configuration or additional content caches might be needed, the following data points are of particular interest.

Content cache pressure

You can use the declarative status report or Activity Monitor to view cache pressure. Cache pressure indicates how urgently the content cache needs more storage space during the reporting period. Lower cache pressure is better.

Cache pressure is the first of the following that applies:

Cache pressure			Calculation
100%			`requestsRejectedForNoSpace > 0`
80%			`bytesPurgedYoungerThan1Day > 0`
60%			`bytesPurgedYoungerThan7Days > 0`
40%			`bytesPurgedYoungerThan30Days > 0`
20%			`bytesPurgedTotal > 0`
0%			`Otherwise`

Processor usage

Check the processor usage for the AssetCache process in Activity Monitor (open Activity Monitor, choose View > All Processes, then click CPU). If the processor usage is constantly at or near 80% across all cores, you may want to add additional content caches to distribute the requests across multiple Mac computers.

Network usage

Check the network download and upload usage in Activity Monitor (open Activity Monitor, choose View > Network). If the download and upload speeds are higher than 70% of the maximum possible utilization of the used interface, do one of the following:

Increase the link speed if possible
Deploy additional content caches close to the clients

Declarative status items

On a Mac with macOS 27, declarative status items provide increased visibility about the status of the content caching service. A device management service can subscribe to the following status updates:

General information about the content cache, such as available and used storage space, status, and cache pressure.
Detailed information about the registration status, IP addresses, report status, and encountered errors.
The list and status of parent content caches.
The list and status of peer content caches.

A status update is sent when the status changes and according to a defined reporting interval.

Metrics report

You can use the content caching configuration to define an arbitrary HTTPS endpoint that the Mac sends information to on a regular, configurable basis. This allows for custom monitoring solutions and dashboards, providing greater insights into how the content caching service is used.

Sending the metrics report to an arbitrary HTTPS endpoint requires macOS 27 and a configuration, which defines the status target, reporting interval, and the security of the connection.

The connection security to the receiving endpoint can be configured with three options:

Use the operating system’s default certificate handling (this also allows for plain HTTP requests, for example, for testing purposes).
The server certificate is validated against a certificate authority provided in the configuration.
The service certificate needs to match the server certificate provided in the configuration.

The content cache sends the current cache status as JSON formatted text using an HTTPS POST request and includes a server-specific ID, which can be used to attribute multiple reports from the same server.

In addition to other data points, specifically the following are of interest when scaling a content caching deployment as they are only available from this status report:

Unique clients: The number of unique IP addresses using the content cache within the reporting period. Use it as a lower bound on how many devices a cache is serving, and compare it across periods.
Peak clients: The peak number of client requests within the reporting period. It should be below 80% of your designed maximum.
Connected clients: The number of client requests being served by the cache when the report was sent. This is a measure of simultaneous activity, not of how many devices the cache serves. A single client may have multiple requests to a cache so this number can exceed the number of unique clients.

You can also deploy an additional content cache if the client numbers exceed their threshold to distribute the load.

Local usage metrics

The following metrics are available on each content cache and provide additional details about its usage.

Content Caching stores metrics in the following folder:

/Library/Application Support/Apple/AssetCache/Metrics.

The metrics are always stored in this location, even if you move the cached content.

If Content Caching has ever been used on a Mac, this folder contains a file named Metrics.db, and may contain one or more other files with similar names. These files constitute a SQLite database that you can read.

The Core Data object model that describes the metrics is available as the “Metric” entity in /usr/libexec/AssetCache/AssetCache.momd.

Important: Although this is a description of the version 7 model, Apple may change this model—or use a database other than SQLite—in future releases of macOS without notice. This may require updates to any scripts you have configured to aggregate caching content data. Use declarative status items and metrics reports sent to an HTTPS endpoint whenever possible.

The content cache:

Adds a new row to the database each minute as it runs
Doesn’t add “all zero” rows when idle; it simply skips adding such rows
Doesn’t modify existing rows
Periodically deletes rows when they’re more than 30 days old

Each row in the database contains the following columns.

Object				Description
bytesDropped				Amount of data the content cache downloaded during the reporting period but couldn’t add to its cache.
bytesFromCacheToChild				Amount of data the content cache served from its cache to child content caches during the reporting period.
bytesFromCacheToClient				Amount of data the content cache served from its cache to client Apple devices during the reporting period.
bytesFromCacheToPeer				Amount of data the content cache served from its cache to peer content caches during the reporting period.
bytesFromOriginToChild				Amount of data the content cache downloaded over the internet and served to child content caches during the reporting period.
bytesFromOriginToClient				Amount of data the content cache downloaded over the internet and served to client Apple devices during the reporting period.
bytesFromOriginToPeer				Amount of data the content cache downloaded over the internet and served to peer content caches during the reporting period.
bytesFromParentToChild				Amount of data the content cache downloaded from parent content caches and served to child content caches during the reporting period.
bytesFromParentToClient				Amount of data the content cache downloaded from parent content caches and served to client Apple devices during the reporting period.
bytesFromParentToPeer				Amount of data the content cache downloaded from parent content caches and served to peer content caches during the reporting period.
bytesFromPeerToChild				Amount of data the content cache received from peer content caches and served to child content caches during the reporting period.
bytesFromPeerToClient				Amount of data the content cache received from peer content caches and served to client Apple devices during the reporting period.
bytesImportedByHTTP				Amount of data the content cache received over HTTP during the reporting period.
bytesImportedByXPC				Amount of data the content cache received over XPC during the reporting period.
bytesPurgedTotal				Amount of data the content cache purged from its cache during the reporting period. Includes `bytesPurgedYoungerThan30Days`.
bytesPurgedYoungerThan1Day				Amount of data the content cache purged from its cache during the reporting period, that it had added to the cache less than one day ago.
bytesPurgedYoungerThan30Days				Amount of data the content cache purged from its cache during the reporting period, that it had added to the cache less than 30 days ago. Includes `bytesPurgedYoungerThan7Days`.
bytesPurgedYoungerThan7Days				Amount of data the content cache purged from its cache during the reporting period, that it had added to the cache less than seven days ago. Includes `bytesPurgedYoungerThan1Day`.
creationDate				Date at which this metrics object was collected. This metrics item describes the content cache’s performance during the period ending at the `creationDate`.
importsByHTTP				Number of upload requests the content cache received via HTTP during the reporting period.
importsByXPC				Number of upload requests the content cache received via XPC during the reporting period.
period				Duration, in seconds, of the reporting period ending at the `creationDate`.
repliesFromCacheToChild				Number of replies the content cache served from its cache to child content caches during the reporting period.
repliesFromCacheToClient				Number of replies the content cache served from its cache to client Apple devices during the reporting period.
repliesFromCacheToPeer				Number of replies the content cache served from its cache to peer content caches during the reporting period.
repliesFromOriginToChild				Number of replies the content cache downloaded over the internet and served to child content caches during the reporting period.
repliesFromOriginToClient				Number of replies the content cache downloaded over the internet and served to client Apple devices during the reporting period.
repliesFromOriginToPeer				Number of replies the content cache downloaded over the internet and served to peer content caches during the reporting period.
repliesFromParentToChild				Number of replies the content cache downloaded from parent content caches and served to child content caches during the reporting period.
repliesFromParentToClient				Number of replies the content cache downloaded from parent content caches and served to client Apple devices during the reporting period.
repliesFromParentToPeer				Number of replies the content cache downloaded from parent content caches and served to peer content caches during the reporting period.
repliesFromPeerToChild				Number of replies the content cache received from peer content caches and served to child content caches during the reporting period.
repliesFromPeerToClient				Number of replies the content cache received from peer content caches and served to client Apple devices during the reporting period.
requestsFromChild				Number of download requests the content cache received from child content caches during the reporting period.
requestsFromClient				Number of download requests the content cache received from client Apple devices during the reporting period.
requestsFromPeer				Number of download requests the content cache received from peer content caches during the reporting period.
requestsRejectedForNoSpace				Number of download requests the content cache rejected during the reporting period due to high cache pressure (with HTTP response code 503, Service Unavailable).

Group results

You might find it helpful to group together some of the above items. Here are some suggestions. All content is integer based.

Content	Grouped objects	Description
Bytes downloaded	bytesFrom <Origin,Parent,Peer>To	Amount of data the content cache downloaded either over the internet or from peers or parents during the reporting period.
Bytes served	Total amount of data the content cache served during the reporting period. When this value is nonzero, the content cache is working.	Sum of bytesFromTo
Bytes served from cache	Sum of bytesFromCacheTo*	Amount of data the content cache served from its cache during the reporting period. The closer this value is to the Bytes served value, the more the content cache helped.
Bytes served from origin	Sum of bytesFromOriginTo*	Amount of data the content cache downloaded over the internet during the reporting period.
Bytes served from parent	Sum of bytesFromParentTo*	Amount of data the content cache downloaded from any of its parent content caches during the reporting period.
Bytes served from peer	Sum of bytesFromPeerTo*	Amount of data the content cache downloaded from any of its peer content caches during the reporting period.
Bytes served to child	Sum of bytesFrom*ToChild	Amount of data the content cache served to any of its child content caches during the reporting period.
Bytes served to client	Sum of bytesFrom*ToClient	Amount of data the content cache served to client Apple devices during the reporting period.
Bytes served to peer	Sum of bytesFrom*ToPeer	Amount of data the content cache served to any of its peer content caches during the reporting period.
Bytes uploaded	Sum of bytesImportedBy*	Amount of data uploaded through the content cache during the reporting period.

Helpful?

Apple Platform Deployment