# Cache Stats

import { Aside } from '@astrojs/starlight/components';

Cache stats show how Avrea's caches behaved during a workflow run or an
individual job. It combines traffic observed by the GitHub Actions, build, and
package caches with supported build-client telemetry.

Cache stats are enabled by default. Individual cache settings still control
which integrations are active, so disabled caches do not report activity.

## Where to find it

In the [Avrea console](https://console.avrea.com):

- Open a workflow run and expand **Run cache activity** for the whole run.
- Expand a job and open **Job cache activity** to isolate one job.
- Open a repository's **Caches** page to see stats from the last 24 hours.

Telemetry is collected by new jobs as they run. It is not backfilled for jobs
that finished before cache telemetry collection was available.

## Reading the cache table

Each row represents one cache scope and layer, such as **GHA · Restore**,
**Go Build · AC**, or **Swift · Package**.

| Column | Meaning |
| --- | --- |
| **Hit rate** | Validated lookup hits divided by hits plus misses. Errors are reported separately. **No lookups** means that no validated lookups were observed, not a 0% hit rate. |
| **Served** | Bytes returned by the cache. The detail line shows transfer requests and lookup errors when supported. |
| **Written** | Bytes successfully uploaded to the cache. The detail line shows successful writes and write errors when supported. |

Transfer rates divide successful bytes by cumulative successful transfer time.
They describe cache transfer throughput, not total job throughput. A transfer
request can be a protocol-level request or range chunk rather than one logical
artifact download.

## Entry diagnostics

Expandable rows can include recent per-entry diagnostics when the cache
protocol exposes a useful identity:

- **GitHub Actions cache** shows the requested key, match outcome, matched key,
  size, and observation time.
- **Package cache** shows the package or artifact, ecosystem and version,
  outcome, downloaded size and rate, and observation time.

Diagnostics are bounded and can be truncated. Aggregate counters still cover
all validated activity included in the summary. The console labels truncated
or invalid diagnostic results instead of presenting them as complete.

## Go and Xcode build-client details

Go and Xcode can report build-client cache stats in addition to cache traffic.
Expand a supported build-cache row to compare:

- Local and remote hit rates
- Lookups, writes, and errors
- Downloaded and uploaded bytes and transfer rates
- Session counts and incomplete sessions

These are cache-operation summaries. They do not include Go package, source
file, function, or Xcode compilation-unit names.

## Gradle task outcomes

Gradle 8.1.1 and later can report task outcomes on Linux and macOS runners when
the **Gradle Build Cache** integration is enabled. Each invocation summarizes:

- Executed, from-cache, up-to-date, skipped, and failed task counts
- The observed task window, excluding build configuration
- Selected task paths, outcomes, and durations

The aggregate counts cover every observed task. The detailed task list is
bounded and prioritizes failed and slower tasks. If details are omitted, the
console shows the omitted count. Telemetry failures do not fail the Gradle
build.

## Coverage states

Cache stats distinguish missing data from zero activity:

| State | Meaning |
| --- | --- |
| **In progress** | The job is running, or telemetry is waiting for its first checkpoint. Counters can still change. |
| **Complete** | Final checkpoints were observed for the expected cache producers. |
| **Partial** | Some expected checkpoints, executions, or diagnostic records were missing, invalid, truncated, or timed out. Displayed counters include only validated data. |
| **Unavailable** | No valid cache checkpoints are available for the selected run or period. This does not mean zero cache traffic. |

<Aside type="note">
Different cache protocols expose different counters and diagnostic fields. A
blank detail section does not imply that the cache integration was disabled.
</Aside>