Watch five signals: cache hit ratio, upstream error rate, authentication failures, metadata freshness, and storage headroom. Together they tell you whether the mirror is helping, whether the public registry is failing behind it, whether tokens are breaking, whether it serves stale data, and whether it is about to run out of room.
Why monitor a mirror at all
A mirror sits in every build's path. When it works, nobody thinks about it. When it fails, every pipeline fails together and the error often looks like a registry problem. Monitoring turns that surprise into an alert. It also gives you evidence for the postmortem.
The five signals
| Signal | What it tells you | Alert idea |
|---|---|---|
| Cache hit ratio | Whether builds are served locally | Sudden drop after a stable period |
| Upstream error rate | Whether the public registry is failing behind you | Errors above your normal rate for several minutes |
| Authentication failures | Expired, revoked or wrong tokens | A rise in 401 or 403 responses |
| Metadata freshness | Whether new versions and removals appear in time | Index older than your expected refresh interval |
| Storage headroom | Disk or object store capacity | Under a set share of free space |
Cache hit ratio
A healthy mirror serves most repeat requests from storage. A falling ratio can mean a cache wipe, a key change, a misrouted client, or a new project fetching a large set of packages. It also predicts load: low hit ratio means more upstream traffic, which means more exposure to upstream limits. See why CI jobs hit pull rate limits.
Upstream error rate
Track what the mirror receives from the public registry. If upstream errors rise while your own clients are fine, the mirror is absorbing an outage for you. That is the good case, and a reason to tell people builds are protected. If clients fail too, the cache was cold for what they needed.
Authentication failures
Separate 401 from 403, since they point to different causes. HTTP references describe a 401 as missing or invalid credentials and a 403 as an understood request that is refused. A rise often follows an expiring token, so link the alert to your rotation calendar. See rotate a CI registry token without breaking builds.
Metadata freshness
Mirrors cache the index that lists versions. If it is stale, a newly released security fix does not appear, and a removed malicious version may still be served. Define how old the index may get and alert past it. Read what happens to your mirror when upstream removes a package for the removal side.
Storage headroom
A caching mirror grows. Alert well before it is full, and decide an eviction rule in advance. Eviction that deletes a package your lockfiles still need turns an outage plan into an outage cause. Settings to review are in pull-through cache proxy settings.
Add a synthetic check
Counters tell you what happened. A synthetic check tells you what a developer would see. Once a minute, fetch a known package through the mirror, with the same client and credentials your builds use, and alert on failure or slowness. It catches a broken certificate or a dead route that metrics miss.
Log what you will need later
Keep request logs long enough to answer "which build pulled this version". See what should an internal registry log for security.
Try it yourself
Click through it at your own pace, or open it full screen.
Watch how a change in a dependency's status surfaces without anyone rerunning a scan, then think about which of the five signals would tell you the same about your mirror.
Where Safeguard fits
Mirror metrics show infrastructure health. Safeguard's continuous dependency scanning shows the risk in what the mirror serves, and asset discovery helps you find pipelines that still bypass it.
Quick check
What is the single most useful alert?
A synthetic fetch that mimics a real build. It fails for any cause, such as certificates, routing, auth or storage.
Who should receive the alerts?
The named owner of the mirror, with an escalation path. Roles and escalation are in the one page mirror runbook.
Sources
Last reviewed: 19 October 2026.
