What it is
GitHub answers most questions about the present and almost none about the past.
The traffic API serves fourteen days and forgets. The activity feed keeps the last three hundred events, whatever their dates. Read notifications disappear within weeks. Job logs are deleted after ninety days. The star list will tell you when each star was given, but only if you ask before the list gets long enough to be expensive to walk. None of it is archived anywhere unless you archive it.
ghchronicle sweeps those surfaces on a schedule and writes every observation
as a point stamped with the date the thing actually happened, so a year from
now the question “how fast were we merging in July” still has an answer.
ghchronicle -config config.yamlIt is one Go binary with no dependencies beyond a YAML parser, and it pushes to every store it supports, so it runs wherever it can reach them: a server, a container, a scheduled workflow.
The six words the rest of this uses
Section titled “The six words the rest of this uses”| Word | What it means here |
|---|---|
| family | One collector, named in the configuration: actions, stars, issues. There are 34 |
| group | A named set of families, for switching a whole area on or off: ci, security, audience. There are 8 |
| measurement | One kind of row in the store, named gh_*: gh_star, gh_workflow_run. There are 91 |
| point | One row: a measurement, its tags, its fields and the date the thing happened |
| sweep | One pass over the families that are due, which is what the process does on a loop |
| backfill | A run with -backfill, which walks the history instead of the increment |
ghchronicle -groups prints the groups with their families, and
ghchronicle -config config.yaml -list prints the repositories a sweep would
cover.
Where to go next
Section titled “Where to go next”- Quickstart: from nothing to a first sweep.
- The token: which scope buys which family.
- Dating a point: the design idea everything else follows from.