# ghchronicle documentation > Collects every metric GitHub exposes about an account and keeps it with the date it happened. This is the index of the ghchronicle documentation site. Every entry links one page and carries that page's own description. Source, issues and releases live at https://github.com/jmrplens/ghchronicle. Home: [ghchronicle](https://jmrplens.github.io/ghchronicle/): Collects every metric GitHub exposes about an account and keeps it with the date it happened. ## Start here - [What it is](https://jmrplens.github.io/ghchronicle/start/): What ghchronicle collects, and the problem it exists to solve. - [Quickstart](https://jmrplens.github.io/ghchronicle/start/quickstart/): From nothing to a first sweep, and what that first sweep does that later ones do not. - [The token](https://jmrplens.github.io/ghchronicle/start/token/): Which scopes buy which families, and why the automatic GITHUB_TOKEN is not enough. ## Installation - [Ways to install](https://jmrplens.github.io/ghchronicle/install/): A page per operating system, four ways to get the binary running, and what each one is good for. - [Linux](https://jmrplens.github.io/ghchronicle/install/linux/): The whole path on Linux: the right archive, the signature, the PATH, a service, and building it yourself. - [macOS](https://jmrplens.github.io/ghchronicle/install/macos/): The whole path on macOS: the darwin archive, quarantine, a launchd agent or daemon, and building it yourself. - [Windows](https://jmrplens.github.io/ghchronicle/install/windows/): The whole path on Windows: the zip, PowerShell and cmd, a scheduled task, and what is genuinely different there. - [systemd](https://jmrplens.github.io/ghchronicle/install/systemd/): A hardened unit for the one process on the host that holds a GitHub token, and what each restriction is for. - [Docker](https://jmrplens.github.io/ghchronicle/install/docker/): The distroless image, what has to be mounted writable, and a compose file next to InfluxDB. - [GitHub Actions](https://jmrplens.github.io/ghchronicle/install/actions/): The composite Action, its three modes, and the two things a hosted runner does not keep. ## Configuration - [The file](https://jmrplens.github.io/ghchronicle/configuration/): One YAML file, every value expandable from the environment, and what each top-level block is for. - [Build the configuration](https://jmrplens.github.io/ghchronicle/configuration/builder/): A form that writes the config.yaml a normal run takes and the workflow step the Action takes, from the binary's own list of settings. - [Targets](https://jmrplens.github.io/ghchronicle/configuration/targets/): Which repositories a sweep touches, and why forks and archived repositories are excluded by default. - [Cadences](https://jmrplens.github.io/ghchronicle/configuration/cadences/): The three layers of the every block, the built-in cadence of every family, the warning when a configuration speeds one up, and the heartbeat. - [Logging](https://jmrplens.github.io/ghchronicle/configuration/logging/): Level, format, the rotating file that never replaces standard error, and the two lines worth alerting on. ## How it works - [The sweep](https://jmrplens.github.io/ghchronicle/how/): What one pass over GitHub does, in what order, and why each family has its own cadence. - [Dating a point](https://jmrplens.github.io/ghchronicle/how/dating/): Every point carries the moment the thing happened, and that single rule decides what the whole project can answer. - [Backfill](https://jmrplens.github.io/ghchronicle/how/backfill/): One deliberate walk to the end of every surface, how far back it goes, and the three things no backfill can reach. ## Collectors - [What is collected](https://jmrplens.github.io/ghchronicle/collectors/): The thirty-four families, what each one asks GitHub for, and the reason each exists. - [Measurements](https://jmrplens.github.io/ghchronicle/collectors/measurements/): Every measurement, its tags, its fields, and how each one is dated. ## Sinks - [Choosing a store](https://jmrplens.github.io/ghchronicle/sinks/): Ten stores, what each one can and cannot answer, and the one property that decides between them. - [InfluxDB](https://jmrplens.github.io/ghchronicle/sinks/influxdb/): The reference store for the dated history, why re-collection converges, and the one write error worth recognising. - [Prometheus](https://jmrplens.github.io/ghchronicle/sinks/prometheus/): An exporter, not a pusher, and what the reduction to current values does to each measurement. - [OpenTelemetry](https://jmrplens.github.io/ghchronicle/sinks/otlp/): OTLP over HTTP with the JSON encoding, and why raw is false by default. - [PostgreSQL](https://jmrplens.github.io/ghchronicle/sinks/postgres/): INSERT statements you pipe into psql, the schema they declare, and why the conflict clause updates rather than does nothing. - [Graphite](https://jmrplens.github.io/ghchronicle/sinks/graphite/): The plaintext protocol over TCP, and the exact metric path, which is the dashboard's contract. - [Elasticsearch](https://jmrplens.github.io/ghchronicle/sinks/elasticsearch/): The bulk API, one index per measurement, and a document id that makes a rewrite replace rather than duplicate. - [Loki](https://jmrplens.github.io/ghchronicle/sinks/loki/): The twenty-two measurements that are events rather than numbers, and the age horizon that keeps a push from being refused. - [Telegraf](https://jmrplens.github.io/ghchronicle/sinks/telegraf/): Line protocol posted to http_listener_v2, and the reason this is one sink instead of a hundred. - [File and stdout](https://jmrplens.github.io/ghchronicle/sinks/file/): A rotating file for a shipper you already run, the simplest durable buffer there is, and line protocol on standard output. ## Dashboards - [Importing](https://jmrplens.github.io/ghchronicle/dashboards/): Five generated Grafana dashboards, one per store, and how to import each of them. - [What they show](https://jmrplens.github.io/ghchronicle/dashboards/panels/): The seventeen sections and their one hundred and fifty two panels, one capture each, and what changes when the store cannot answer. ## The card - [Overview](https://jmrplens.github.io/ghchronicle/card/): A self-contained SVG for a profile README, drawn from the same points the databases receive. - [Layouts](https://jmrplens.github.io/ghchronicle/card/layouts/): Thirteen layouts in two visual families, with what each one draws by default, which of them animate and which of them can keep going. ## API usage - [Rate limits](https://jmrplens.github.io/ghchronicle/api/): GitHub runs fifteen independent budgets; three of them matter here, and the brake is scaled to each. - [Cost of a sweep](https://jmrplens.github.io/ghchronicle/api/cost/): The measured price of one sweep, per family, and which families to lengthen when the budget is tight. - [What GitHub will not give](https://jmrplens.github.io/ghchronicle/api/limits/): The endpoints that are verified not to work on a personal account, written down so nobody rediscovers them. ## Reference - [The command line](https://jmrplens.github.io/ghchronicle/reference/cli/): The flags, what each one does, and which of them print something and exit. - [Calling it from a program](https://jmrplens.github.io/ghchronicle/reference/subprocess/): There is no Go library. What there is instead is one sweep, NDJSON on standard output, and good reasons not to call it in a loop. - [Troubleshooting](https://jmrplens.github.io/ghchronicle/reference/troubleshooting/): The messages that look like errors and are not, the ones that are, and the data that looks wrong and is not. - [The test layers](https://jmrplens.github.io/ghchronicle/reference/testing/): Three layers, only one of them free: the contract test of the bytes, the containerised stores that accept them, and the dashboards' own queries. ## Machine-readable references - [Full documentation](https://jmrplens.github.io/ghchronicle/llms-full.txt) (436 KB): every English page concatenated, in this order Every page listed above is also served as markdown at its own path with `index.md` appended, which is the cheapest way to read one page as text. ## Other languages - [Spanish documentation index](https://jmrplens.github.io/ghchronicle/es/llms.txt): the same documentation in Spanish, page for page