ghchronicle

91measurements

34collectors

10outputs

152dashboard panels

Every one of them carries the date the thing happened, which is what makes a question about last July still have an answer.

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. Job logs are deleted after ninety days.

ghchronicle sweeps those surfaces on a schedule and writes every observation as a dated point, into whichever database you already run. One Go binary, no dependencies beyond a YAML parser.

Who it is for

• Anyone who already runs a time series database and a Grafana
• Maintainers who want traffic and stars kept past GitHub's window
• Teams who want merge times, review load and CI cost as history rather than as a number that resets
• Anyone who wants their own data out of GitHub before GitHub drops it

What it is not

• Not a hosted service: it runs on your machine, with your token
• Not a replacement for GitHub Insights, which answers about now
• Not able to recover what GitHub has already dropped: it starts from the day you run it
• Not a badge generator, though it can draw one

What it looks like in use

Three steps, and the first sweep lands in your database.

Install

A single binary, or a release, or the container image.

go install github.com/jmrplens/ghchronicle/cmd/ghchronicle@latest

Configure

The smallest configuration that does something. Every ${VAR} is read from the environment, so this file holds no secrets.

github:
  token: ${GITHUB_TOKEN}
targets:
  user: your-login
sinks:
  influxdb:
    url: http://localhost:8181
    bucket: github

Collect

What lands in the database. Note the timestamps: the star is dated 2024, not today, because that is when it was given.

gh_star,repo=parser,user=someone starred=1i 1731590400000000000
gh_traffic,repo=parser,kind=views count=142i,uniques=61i 1757376000000000000
gh_pull_request,repo=parser,number=318,state=MERGED churn=214i,seconds_to_merge=5820i 1757462400000000000

How it is shaped

Four ideas, and the second is the one everything else follows from.

1. Sweep

   Each family of metrics has its own cadence, because they move at very different speeds: workflow runs every quarter of an hour, the contribution calendar every twelve.

2. Date

   A point carries the moment the thing happened, not the moment it was collected. That is what makes re-collection converge instead of accumulating copies.

3. Push

   Nothing here is scraped. It pushes to InfluxDB, PostgreSQL, Graphite, Elasticsearch, Prometheus, OpenTelemetry, Loki, Telegraf, a file or anything Telegraf can reach, so it runs wherever it can reach them.

4. Draw

   One dashboard specification, rendered once per store. The same panels whichever database you chose, and where a store cannot answer one honestly, the panel says so.

Where to start

QuickstartFrom nothing to a first sweep.The tokenWhich scopes, and why the automatic one is not enough.Dating a pointThe idea the rest of the design follows from.Choosing a storeWhat each of the 10 can and cannot answer.