Storage insights & benchmarks

CAVS measures your data rather than estimating it. This page explains what each number means and where it comes from, so you can act on it.

Logical vs physical

Two numbers, everywhere:

	Definition	What it’s for
Logical bytes	The sum of your objects’ nominal sizes. What a naive store would need.	“how much data do we have?”
Physical bytes	The unique compressed bytes actually stored, after chunk dedup.	“what are we paying for?”

The dedup ratio is 1 − physical / logical, shown as a percentage saved.

Don't sum per-object physical sizes

Each object reports its own physical_size — the stored footprint of its chunks. Adding those up across a repository over-counts, because a chunk shared by two objects is counted in both. A repository’s true physical size is the unique packed bytes under its storage namespace, and that’s what the usage worker reports at the repository and organization level. Use the repository figure for billing questions and the per-object figure only for comparing objects to each other.

Quotas and overage are billed on physical managed storage. BYOS physical bytes are not metered by CAVS at all — you pay your provider.

Repository usage

export API=https://cavsnode.com/api/v1
export H="Authorization: Bearer $CAVS_TOKEN"

curl -sS "$API/repositories/$REPO/usage" -H "$H"

Returns logical bytes, physical bytes, object count, egress for the period and the current generation. It reads a reconciled snapshot rather than scanning live, so it’s cheap to poll — and it lags a push by seconds.

How reconciliation works

Finalizing a push publishes repository.usage.changed. The worker sums the real stored bytes under the repository’s namespace directly from the object store and writes the daily usage snapshot the dashboard reads. If the object store is temporarily unreachable it falls back to a conservative estimate and retries — so a figure can briefly be approximate, never silently wrong for long.

Storage over time

curl -sS "$API/repositories/$REPO/storage/series?days=90"  -H "$H"
curl -sS "$API/organizations/acme-ai/usage/series?days=90" -H "$H"

days is 1–365 (default 90). Both return daily points of logical bytes, physical bytes and object count. This is the chart that tells you whether growth is linear (expected) or stepped (someone committed a dataset).

Where the bytes are

# Roll up the indexed tree by directory
curl -sS "$API/repositories/$REPO/storage/folders?depth=2&limit=20" -H "$H"

# Summary: totals, dedup ratio, biggest objects
curl -sS "$API/repositories/$REPO/storage/summary" -H "$H"

# Raw object list, largest first
curl -sS "$API/repositories/$REPO/objects?sort=size&limit=20" -H "$H"

Parameter	Range	Default
depth	1–5	1
limit	1–100	20
ref	any indexed ref	default branch

Folder roll-ups need the Git index — the data plane alone has no directories.

Organization-wide, the Storage view ranks repositories by physical size and groups them by storage group, which is usually enough to find the surprise.

Transfer benchmarks

When the CAVS transfer agent handles a transfer it reports what it actually did. Those records are your benchmarks — measured, not modelled.

curl -sS "$API/repositories/$REPO/transfers?kind=push&limit=10" -H "$H"
curl -sS "$API/repositories/$REPO/transfers?kind=pull&limit=10" -H "$H"

Field	Meaning
kind	push or pull
duration_ms	Wall clock for the whole transfer
ingest_ms	Chunking, hashing and packing (push)
mirror_ms	Uploading the static tree (push)
logical_bytes	Nominal size of what was transferred
stored_bytes	Bytes that actually hit storage (push)
object_count, chunk_count	How many objects and chunks were involved
new_chunks / reused_chunks	The dedup story for this transfer
files_put / files_skipped	Tree files written vs already present

Pull records additionally report wire bytes vs logical bytes, chunks fetched vs reused from cache, and a timing breakdown (metadata, plan, payload, reconstruct).

What good looks like

Signal	Healthy	Investigate
reused_chunks / chunk_count on a small edit	high (> 80%)	near zero — your format probably reshuffles on write
stored_bytes / logical_bytes on a re-push	small	≈ 1 — nothing deduped; check the agent is actually wired
Pull wire bytes with a warm cache	small fraction of logical	≈ logical — cold cache, or the object changed wholesale
ingest_ms share of duration_ms	modest	dominant — CPU-bound chunking; consider a coarser chunk profile

The dashboard’s Benchmarks tab plots throughput in MB/s, dedup percentage, wire savings and the timing breakdown per transfer.

Note

Standard git-lfs transfers produce no benchmark records — there’s no CAVS code in the path to measure them. An empty Benchmarks tab usually means the agent isn’t installed. Run cav doctor.

Health checks

curl -sS "$API/repositories/$REPO/health" -H "$H"

The worker evaluates each repository periodically and reports findings such as:

• Stale branches — no commits in over 30 days.
• Oversized branches — more than 2× the default branch’s footprint.
• Low dedup ratio — the stored bytes are close to the logical bytes.
• Unindexed refs — the dashboard can’t show part of the repository.
• Dominant objects — a single object accounts for most of the repository.

Storage-connection health for BYOS repositories is probed separately; a failing connection raises a notification and marks the connection unhealthy. See Bring Your Own S3.

Recommendations

Actionable suggestions derived from the same analysis:

curl -sS "$API/repositories/$REPO/recommendations?status=open" -H "$H"
curl -sS "$API/organizations/acme-ai/recommendations"          -H "$H"

# Dismiss one you've judged and rejected
curl -sS -X POST "$API/repositories/$REPO/recommendations/$REC_ID/dismiss" -H "$H"

status accepts open or dismissed. Dismissing requires repository.update.

Forecasting

The organization dashboard projects storage and egress to the end of the billing period from the current trend, alongside the plan’s included amounts and the overage that would result:

curl -sS "$API/organizations/acme-ai/dashboard" -H "$H"

This is a linear projection from recent usage, not a promise. Treat a forecast that crosses your plan’s limit as a prompt to look at the folder breakdown, not as a bill.

A practical audit

1. GET /organizations/{org}/dashboard — is total growth expected?
2. GET /organizations/{org}/usage/series?days=90 — is it linear or stepped?
3. Rank repositories by physical size in the Storage view. Anything surprising?
4. For the top repository: GET …/storage/folders?depth=3 — which directory?
5. GET …/objects?sort=size&limit=20 — which objects specifically?
6. GET …/artifacts/{oid}/timeline — which commit introduced it, and is it still referenced?
7. GET …/branches — is a stale branch pinning objects nothing current needs?
8. GET …/recommendations — has CAVS already spotted it?

Then act: delete the stale branch, retag, and let GC reclaim the unreferenced chunks.

Next

• Deduplication explained — why your ratio is what it is.
• Lifecycle & maintenance — GC, repack, compaction.
• Usage & metering — how usage becomes a bill.