# What it is

What ghchronicle collects from GitHub, and the problem it exists to solve: traffic kept for fourteen days, an event feed of three hundred events and thirty days.

Source: https://docs.jmrp.io/ghchronicle/start/

GitHub answers most questions about the present and almost none about the past.

The [traffic API](https://docs.github.com/en/rest/metrics/traffic) serves fourteen days and
forgets. The [activity feed](https://docs.github.com/en/rest/activity/events) keeps the last
three hundred events, and none older than thirty days. The
[notification inbox](https://docs.github.com/en/subscriptions-and-notifications/concepts/about-notifications#notification-retention-policy)
drops every notification after three months, read or not, unless it was saved.
[Job logs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository)
are deleted after ninety days by default. The star list will tell
you when each star was given, but since July 2026 only to a repository's
[admins and collaborators](https://docs.github.com/en/rest/activity/starring#new-access-restrictions),
and 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.

```sh
ghchronicle -config config.yaml
```

It is one static Go binary with no runtime dependencies, and it pushes to every
store it supports, so it runs wherever it can reach them: a server, a
container, a scheduled workflow.

> **The card is not the point**
>
> It can also draw an SVG summary card for a profile README. That is a side
> feature. The reason the project exists is the ingestion.

## 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 95               |
| **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

- [Quickstart](https://docs.jmrp.io/ghchronicle/start/quickstart/): from nothing to a first sweep.
- [The token](https://docs.jmrp.io/ghchronicle/start/token/): which scope buys which family.
- [Dating a point](https://docs.jmrp.io/ghchronicle/how/dating/): the design idea everything else
  follows from.