Content caching metrics on Mac
Content Caching stores metrics in the following folder:
/Library/Application Support/Apple/AssetCache/Metrics.
The metrics don’t move with the cached content; instead, they’re always stored in this location. For example, if you move the cache from:
/Library/Application Support/Apple/AssetCache/Data
to
/Volumes/Data/Library/Application Support/Apple/AssetCache/Data
metrics are still stored in
/Library/Application Support/Apple/AssetCache/Metrics
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 CoreData object model that describes the metrics is available as the “Metric” entity in /usr/libexec/AssetCache/AssetCache.momd.
Note: Although this is a description of the version 7 model here, 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.
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
Tip: You can change the reporting time period from 60 seconds by changing the MetricsInterval advanced setting, and you can change the maximum age of stored rows from 30 days by changing the MetricsMaxAge advanced setting.
Each row in the database contains the following columns. Every object is optional except for creationDate.
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 7 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 bytesFrom*To* | |||||||||
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. | |||||||||
Get cache pressure data
You can review how urgently the content cache needed more storage space during the reporting period. Lower cache pressure is better.
Activity Monitor calculates cache pressure as follows:
100% when requestsRejectedForNoSpace > 0
80% when bytesPurgedYoungerThan1Day > 0
60% when bytesPurgedYoungerThan7Days > 0
40% when bytesPurgedYoungerThan30Days > 0
20% when bytesPurgedTotal > 0
0% otherwise
Activity Monitor also collates the above items as follows, for instance to calculate values over a time interval longer than one period.
For byte counts, import counts, request counts, or response counts, sum them over the time interval.
For cache pressure, calculate the maximum over the time interval.
Sample code for reading the metrics database
#import <Foundation/Foundation.h>#import <CoreData/CoreData.h>void readMetricsSinceDate(NSDate *date){NSURL *modelURL = [NSURL fileURLWithPath:@"/usr/libexec/AssetCache/AssetCache.momd"];NSManagedObjectModel *model = [[NSManagedObjectModel alloc] initWithContentsOfURL:modelURL];if (model == nil) {// handle the error }NSPersistentStoreCoordinator *coordinator = [[NSPersistentStoreCoordinator alloc] initWithManagedObjectModel:model];NSURL *databaseURL = [NSURL fileURLWithPath:@"/Library/Application Support/Apple/AssetCache/Metrics/Metrics.db"];NSError *storeError = nil;NSPersistentStore *store = [coordinator addPersistentStoreWithType:NSSQLiteStoreType configuration:nil URL:databaseURL options:@{ NSReadOnlyPersistentStoreOption: @YES } error:&storeError];if (store == nil) {// handle the error }NSManagedObjectContext *context = [[NSManagedObjectContext alloc] initWithConcurrencyType:NSPrivateQueueConcurrencyType];context.persistentStoreCoordinator = coordinator;NSFetchRequest *request = [NSFetchRequest fetchRequestWithEntityName:@"Metric"];request.predicate = [NSPredicate predicateWithFormat:@"%K > %@", @"creationDate", date];request.sortDescriptors = @[ [NSSortDescriptor sortDescriptorWithKey:@"creationDate" ascending:YES] ];NSError *fetchError = nil;NSArray *results = [context executeFetchRequest:request error:&fetchError];if (results == nil) {// handle the error }for (NSManagedObject *result in results) {NSNumber *bytesDropped = [result valueForKey:@"bytesDropped"];// ...NSNumber *requestsRejectedForNoSpace = [result valueForKey:@"requestsRejectedForNoSpace"];// use the values }}