mirror of https://github.com/boshu2/agentops.git synced 2026-09-14 15:08:13 +08:00

Files

T

boshu e0bcea403a feat(metrics): GitHub traffic capture harness (age-5l6c)

The literal 'harness these metrics' ask. GitHub's traffic API is a 14-day
rolling window, top-10 only — every read evaporates. Without a periodic capture,
'what do people use?' is forever a thin 14-day guess.

- scripts/capture-repo-metrics.sh: append one dated JSON snapshot (stars/forks/
  watchers/open-issues, 14d views+clones total/unique, top-10 paths + referrers)
  to docs/metrics/traffic.jsonl. --dry-run previews. Fails CLOSED (no partial
  record) if gh is missing/unauthenticated or any endpoint fetch fails.
- docs/metrics/README.md: the instrument doc + the one trap baked into every
  record (clones_note): clones is NOT users (CI/mirrors/scrapers — ~43k clones
  vs ~1k views in one window); rank interest by unique path views + fork velocity.
- docs/metrics/traffic.jsonl: seeded baseline (399 stars, 40 forks, 4 watchers;
  #1 viewed content = operating-loop.js).
- tests/scripts/capture-repo-metrics.bats: hermetic gh-stub tests — record shape,
  append, fail-closed on unauth + on endpoint failure.

Scheduling is the operator's (cron/launchd/substrate); AgentOps ships no daemon
(ADR-0009). The script is the artifact, the cadence is yours.

2026-06-26 21:39:46 -04:00

README.md

feat(metrics): GitHub traffic capture harness (age-5l6c)

2026-06-26 21:39:46 -04:00

traffic.jsonl

feat(metrics): GitHub traffic capture harness (age-5l6c)

2026-06-26 21:39:46 -04:00

README.md

Repo metrics harness

A longitudinal record of who looks at this repo and what they open. GitHub's traffic API is a 14-day rolling window, top-10 only — every read evaporates. This harness snapshots it on a schedule so the signal accumulates into a trend instead of a thin two-week guess.

Files

traffic.jsonl — one JSON record per capture (append-only). Each line carries the date, stars/forks/watchers/open-issues, 14-day views and clones (total + unique), the top-10 viewed paths, and the top-10 referrers.
../../scripts/capture-repo-metrics.sh — the capture. Fails closed (writes no partial record) if gh is missing/unauthenticated or any endpoint fails.

Run it

scripts/capture-repo-metrics.sh              # append a snapshot for boshu2/agentops
scripts/capture-repo-metrics.sh --dry-run    # preview the record, write nothing
scripts/capture-repo-metrics.sh owner/repo   # any repo you have push access to

Traffic endpoints need push access to the repo (that's a GitHub API rule, not ours). Schedule it however you run out-of-session work — cron, launchd, or the AgentOps substrate. AgentOps ships no daemon (ADR-0009); the script is the artifact, the cadence is yours. Weekly is plenty (the window is 14 days, so weekly captures overlap and lose nothing).

Reading it — the one trap

clones is not users. It is dominated by CI, package mirrors, and scrapers — a real window showed ~43k clones against ~1k views. Never cite clones as adoption. Rank human interest by:

unique PATH views (top_paths[].uniques) — what people actually open.
fork velocity (forks delta between snapshots) — who clones to use.
stars delta — attention, not commitment (watchers is the commitment tell).

The record bakes this caveat into every line as clones_note so a future reader can't miss it.

Why this is part of "rock solid"

Distribution (stars) is not the same as value delivered. None of these numbers measure whether the verification membrane caught anyone's bad "done" — they measure attention and intent-to-try. This harness turns a one-shot screenshot into the trend you'd need before claiming retention or value, and keeps the next "what do people use?" answer grounded in accumulated data rather than a 14-day snapshot.