Data Collection

Where Content Caching Monitor gets its numbers — and, just as usefully, what those numbers cannot tell you.

Overview

There is exactly one source: the status report each caching server sends. Everything on screen — every KPI, every chart, every table — is derived from those reports and nothing else.

This builds on push reporting, introduced in macOS 27. The caching service sends a status report by itself, on a schedule, to a URL you nominate. Each server reports in on its own — there is nothing to log into, no credentials to keep on each machine, and nothing going out to ask.

The consequence: caching servers must run macOS 27 or later. There is no fallback to log reading, and a server on macOS 26 cannot be monitored at all — it will accept the configuration and then silently never report.

The Status Report

Push Report Live

Configured by: ManagementStatusTarget and ManagementReportingInterval on the caching server

A JSON document describing the server at that moment, sent every interval whether or not anything happened. It carries five groups of fields:

GroupContains
Identity & statusServer GUID, host name, version, whether it is active and registered, listening port, public and private addresses
CapacityBytes used, free and limit; entry counts; an asset-size histogram; and cacheDetails — what is stored, by content category
TopologyConfigured parents and peers, and the selection policy between them
Client activityConnected, peak and unique clients; transactions; and recentErrors, a response-code histogram
MetricsThe full counter block — bytes and replies from cache, origin, parent and peer, split by destination; imports; purges by age; requests rejected for want of space
The metrics block is conditional. When a period was completely idle, the caching service omits it entirely rather than sending zeros. Every counter is therefore treated as optional and defaulted to zero — a quiet server is not a broken one.

Two fields arrive as text rather than structure, and are parsed on the way in:

// cacheDetails — a display string, not a dictionary
"Mac Software : 39457280000, iOS Software : 59055800000, Other : 7106427"

// recentErrors — httpStatus:reasonCode:count
"200:10:1, 304:10:6"

How a Report Reaches the App

Two paths, and the difference between them is what happens when your Mac is not listening.

  ┌──────────────┐   loopback    ┌───────────┐   LAN, retried   ┌──────────────┐
  │  AssetCache  │──────────────▶│ ccm-agent │─────────────────▶│ ccm-collector│──▶ app
  │  (macOS 27)  │               │  (spool)  │                  │   fleet.db   │
  └──────┬───────┘               └───────────┘                  └──────▲───────┘
         │                                                              │
         └──────────────────  LAN, no spool, no retry  ─────────────────┘

Agent-assisted reporting. The caching service posts to the agent on its own machine, over loopback. The agent writes the report to disk, then forwards it and keeps trying until it succeeds. Nothing is lost while your Mac is asleep, quit or signed out.

Direct reporting. The caching service posts straight to your Mac. Nothing to install, and nothing to catch a report that arrives while your Mac is unavailable — the caching service empties its accumulator when it attempts a send, not when one succeeds, and never retries. Good for trying the app out; for a fleet you rely on, use agent-assisted reporting.

Approval comes first. A server that reports for the first time creates a request, not a record. Nothing it sends is stored or counted until you approve it in the sidebar — and until then its reports are discarded rather than held.

Up to ten servers. The App Store edition admits up to ten caching servers across all your sites, direct and agent-assisted alike. A server that has gone quiet still holds its place; removing one from the fleet frees it. For larger fleets, an enterprise edition is available — write to hello@ooz.ch.

What the App Derives

From Report to Panel Derived

Shown asDerived from
Data servedEverything the servers served — to devices, child caches and peers — summed over the period
Bandwidth savedBytes served from the servers' own caches — what did not have to be fetched again
Cache efficiencyBytes from cache, as a share of bytes served
Peak throughputThe heaviest 15-minute window in the period, converted to Gbps, and warned about as a share of each server's own link
Cache pressureA tiered 0–100 scale from purge activity, following Apple's own definition
Cache compositioncacheDetails, across Apple's nine content categories
Traffic destinationsThe client / peer / child split of the same counters
Response codesrecentErrors, which despite its name counts successes too
Coverage gapsIntervals where a report was expected and none arrived — counted for the gaps check and content_caching_gaps_recent, not shown in the app

The parents and peers each server reports are recorded too. A site's subtitle counts its parents, children and standalone servers; no view draws the topology, and peers are shown nowhere yet.

Cache pressure is a severity ladder rather than a percentage of anything:

ValueConditionMeaning
100%Requests rejected for no spaceCritical — add storage now
80%Content purged within a day of arrivingHigh
60%Content purged within seven daysElevated
40%Content purged within thirty daysModerate
20%Some old content purgedLow
0%No purgingHealthy — the cache is still growing

Reading the Two Headline Figures

Cache efficiency and cache pressure sit side by side, and they answer different questions. Knowing which is which saves a lot of second-guessing.

Cache Efficiency — how much you saved

Of everything served during the period, the share that came off local disk rather than being fetched from Apple. High is good: it is the proportion of your traffic that never crossed your internet connection.

For a site, it is weighted by traffic, not averaged across servers. A site with ten caches where nine sat idle at 95% and one did all the work at 20% reads about 20%, not 87%. That is deliberate — it answers “what did this site actually save”, and an average would flatter you with figures from servers that barely did anything.

A low number is not automatically a fault. A cache that has just been installed, or has just been cleared, has nothing to serve from yet and has to fetch everything once. Look at the trend over a few days rather than the figure in front of you.

Reports that straddle the edge of the period are counted in proportion. A report covering five minutes either side of midnight contributes half its bytes to each day, so a period boundary never double-counts traffic or drops it.

Cache Pressure — whether anything is struggling

How hard the cache is having to discard content to make room, on Apple's 0–100 scale. It is not how full the disk is: a cache can be completely full and sit at 0 if nothing is being evicted.

It shows the worst moment, and the worst server. A site reads 80 if any one of its caches reached 80 at any point in the period. It never averages down, because one machine thrashing is exactly the thing you want to see — and an average across ten healthy servers would hide it.

Two consequences worth remembering:

What to do about it. 20 to 40 is ordinary housekeeping — old content ageing out. 60 and above means content is being discarded within a week of arriving, so devices are re-downloading things you already paid for. 100 means requests were refused outright for want of space: add storage, or raise the cache limit in the caching server's own settings.

What the Reports Do Not Contain

Known Limits

Worth stating plainly, because each of these is a question the data cannot answer — not a feature awaiting implementation.

Storage

Every report lands in a single database, shared between the app and the collector that receives them:

~/Library/Group Containers/X9V4XP9PRE.group.net.oneoverzero.contentcachingfleetmonitor/
    └── fleet.db     # reports, metrics, cache details, response codes, topology

It stays on your Mac. Reports travel from your caching servers to your machine and no further — there is no cloud service in the middle and no account to create.

Settings > General > Database > Keep reports for caps how long reports are kept — three, six or twelve months, or forever, which is the default. Settings > General > Maintenance deletes everything collected so far in one step. Neither touches your servers: they stay enrolled, keep their approvals, and go on reporting.