`fx worktree` Telemetry & Metrics

fx worktree tracks developer worktree utilization over time to understand average checkout usage, capacity requirements, resource consumption, and the proportion of checkouts built recently vs. not built recently.

To avoid running background daemons while providing continuous statistical precision, fx worktree uses local piecewise-constant time integration combined with a 24-hour periodic snapshot upload.

Architecture Overview

Local State Accumulation (.fx/metrics/worktree_metrics.json):
- Whenever any fx worktree command executes, the tracker records the current number of total, leased, built recently (built in the last 7 days), and not built recently worktrees.
- The elapsed time since the previous state change is integrated into a running Riemann sum.
- Running minimum and maximum (peak) counts are updated across all four dimensions.
Daily Snapshot Upload:
- On the first fx worktree command executed after 24 hours have passed since period_start_ts, the tracker finalizes the 24-hour time-weighted statistics.
- A single custom telemetry event is dispatched to Fuchsia's Google Analytics 4 (GA4) pipeline via tools/devshell/lib/metrics_custom_report.sh.
- The metrics file is rotated with a fresh 24-hour window starting at the current timestamp and state.

Mathematical Formulation: Time-Weighted Average

Worktree counts change only at discrete events (add, remove, lease, release, build activity). Between events, the count remains constant. Over any interval $[T_0, T_{\text{upload}}]$, the time-weighted average $\bar{N}$ is given by:

$$ \bar{N} = \frac{1}{T_{\text{upload}} - T_0} \int_{T_0}^{T_{\text{upload}}} N(t),dt = \frac{\sum_{i=1}^{k} N_i \cdot \Delta t_i}{T_{\text{upload}} - T_0} $$

Where:

$N_i$ is the count during step $i$.
$\Delta t_i = t_i - t_{i-1}$ is the duration spent in that state.
$T_{\text{upload}} - T_0$ is the total elapsed time of the measurement window.

This ensures accurate representation of developer usage across overnight and multi-day periods without active polling.

Local State Schema

The state file is stored at .fx/metrics/worktree_metrics.json in the root checkout directory, ensuring that all worktrees in the pool share and update the same state:

{
  "period_start_ts": 1756740000.0,
  "last_change_ts": 1756783200.0,
  "current_total": 4,
  "current_leased": 2,
  "current_built_recently": 3,
  "current_not_built_recently": 1,
  "accumulated_total_seconds": 345600.0,
  "accumulated_leased_seconds": 172800.0,
  "accumulated_built_recently_seconds": 259200.0,
  "accumulated_not_built_recently_seconds": 86400.0,
  "min_total": 2,
  "max_total": 5,
  "min_leased": 0,
  "max_leased": 3,
  "min_built_recently": 1,
  "max_built_recently": 4,
  "min_not_built_recently": 0,
  "max_not_built_recently": 2
}

Field Descriptions

period_start_ts: Epoch timestamp (seconds) when the current 24-hour measurement window began.
last_change_ts: Epoch timestamp (seconds) when the count was last updated or sampled.
current_total: Current total number of physical worktree slots in the pool.
current_leased: Current number of worktrees actively leased by a task or developer.
current_built_recently: Current number of worktrees that have been built within the last 7 days.
current_not_built_recently: Current number of worktrees that are unbuilt or whose last build occurred > 7 days ago (current_total - current_built_recently).
accumulated_total_seconds: Integrated time-area product ($\sum N_{\text{total}} \cdot \Delta t$) in second-units.
accumulated_leased_seconds: Integrated time-area product ($\sum N_{\text{leased}} \cdot \Delta t$) in second-units.
accumulated_built_recently_seconds: Integrated time-area product ($\sum N_{\text{built_recently}} \cdot \Delta t$) in second-units.
accumulated_not_built_recently_seconds: Integrated time-area product ($\sum N_{\text{not_built_recently}} \cdot \Delta t$) in second-units.
min_* / max_*: Minimum and peak counts observed across each category within the measurement window.

Telemetry Event & GA4 Attribution

When the 24-hour window expires, fx worktree emits a custom event via tools/devshell/lib/metrics_custom_report.sh:

Subcommand: worktree
Action: daily_snapshot
Label Structure (compact JSON with short keys):
```
{"at":3.0,"mnt":2,"mxt":4,"al":2.0,"mnl":1,"mxl":3,"abr":2.0,"mnbr":1,"mxbr":3,"anbr":1.0,"mnnbr":1,"mxnbr":1}
```
- at, mnt, mxt: Average, min, and max total worktrees
- al, mnl, mxl: Average, min, and max leased worktrees
- abr, mnbr, mxbr: Average, min, and max worktrees built recently
- anbr, mnnbr, mxnbr: Average, min, and max worktrees not built recently

Seamless Pipeline Attribution

Because metrics_custom_report.sh forwards the open metrics stream (file descriptor 10) from scripts/fx, the event is automatically joined in the same batch with:

Client ID (client_id): Persistent anonymized METRICS_UUID.
Cross-Tool ID (other_uuid): Correlation UUID for ffx, zxdb, and VS Code tools.
User Properties: internal (Googler vs external), is_cog (Cloud Cog vs local workstation), os, arch, and nproc.

Privacy and Data Governance

In compliance with Fuchsia's Analytics Policy:

Only aggregate statistical numbers (averages, minimums, peaks) are uploaded.
No local paths, branch names, worktree identifiers, or task IDs are collected or transmitted.
Telemetry strictly honors user opt-out preferences (fx metrics disable or ffx config analytics disable).

fx worktree Telemetry & Metrics