# ghchronicle documentation > ghchronicle is an open-source tool that collects every metric GitHub exposes about an account and keeps each one 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. Every page listed here is also served as markdown at its own path with `index.md` appended, which is the cheapest way to read one page as text. Home: [ghchronicle](https://docs.jmrp.io/ghchronicle/): ghchronicle is an open-source tool that collects every metric GitHub exposes about an account and keeps each one with the date it happened. ## Start here - [What it is](https://docs.jmrp.io/ghchronicle/start/): 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. - [Quickstart](https://docs.jmrp.io/ghchronicle/start/quickstart/): Install ghchronicle, point it at a database and run a first sweep of a GitHub account, and what that first sweep does that later ones do not. - [The token](https://docs.jmrp.io/ghchronicle/start/token/): Which GitHub token scopes buy which ghchronicle families, and why the automatic GITHUB_TOKEN of a workflow is not enough. - [Compared with the alternatives](https://docs.jmrp.io/ghchronicle/start/compared/): ghchronicle beside GitHub Insights, repohistory, github-repo-stats, star-history and the Prometheus exporters: what each keeps, how long, and where. - [Short answers](https://docs.jmrp.io/ghchronicle/start/questions/): Twelve questions about keeping GitHub history with ghchronicle: traffic past 14 days, stars over time, backfill, Prometheus, organisations and cost. ## Installation - [Ways to install](https://docs.jmrp.io/ghchronicle/install/): Ways to install ghchronicle: a page per operating system, five ways to get the binary running, and what each one is good for. - [Linux](https://docs.jmrp.io/ghchronicle/install/linux/): The whole path on Linux: the right archive, the signature, the PATH, a service, and building it yourself. - [macOS](https://docs.jmrp.io/ghchronicle/install/macos/): The whole path on macOS: the darwin archive, quarantine, a launchd agent or daemon, and building it yourself. - [Windows](https://docs.jmrp.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://docs.jmrp.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://docs.jmrp.io/ghchronicle/install/docker/): Running ghchronicle in Docker: the distroless image, what has to be mounted writable, and a compose file next to InfluxDB. - [GitHub Actions](https://docs.jmrp.io/ghchronicle/install/actions/): Running ghchronicle as a GitHub Action: the composite Action, its four modes, and the two things a hosted runner does not keep. - [Upgrading](https://docs.jmrp.io/ghchronicle/install/upgrading/): What the first hours after an upgrade from 2.5.x to 2.6.x look like, each of them once and on purpose, and what 2.6.1 changes in a store written before it. ## Configuration - [The file](https://docs.jmrp.io/ghchronicle/configuration/): The ghchronicle configuration: one YAML file, its credentials, addresses and paths expandable from the environment, and what each top-level block is for. - [Build the configuration](https://docs.jmrp.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://docs.jmrp.io/ghchronicle/configuration/targets/): Which repositories a sweep touches, and why forks and archived repositories are excluded by default. - [Cadences](https://docs.jmrp.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://docs.jmrp.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://docs.jmrp.io/ghchronicle/how/): What one ghchronicle sweep over the GitHub API does, in what order, and why each family of metrics has its own cadence. - [Dating a point](https://docs.jmrp.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://docs.jmrp.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://docs.jmrp.io/ghchronicle/collectors/): The thirty-four families of GitHub metrics ghchronicle collects, what each one asks the API for, and the reason each exists. - [Measurements](https://docs.jmrp.io/ghchronicle/collectors/measurements/): Every measurement ghchronicle writes from the GitHub API, its tags, its fields, and how each one is dated. ## Sinks - [Choosing a store](https://docs.jmrp.io/ghchronicle/sinks/): Where to store GitHub metrics: eleven stores, what each one can and cannot answer, and the one property that decides between them. - [InfluxDB](https://docs.jmrp.io/ghchronicle/sinks/influxdb/): The reference store for the dated history, why re-collection converges, and the one write error worth recognising. - [Prometheus](https://docs.jmrp.io/ghchronicle/sinks/prometheus/): GitHub metrics in Prometheus: an exporter, not a pusher, and what the reduction to current values does to each measurement. - [OpenTelemetry](https://docs.jmrp.io/ghchronicle/sinks/otlp/): Sending GitHub metrics to an OpenTelemetry collector or to Prometheus: OTLP over HTTP with the JSON encoding, and why raw is false by default. - [PostgreSQL](https://docs.jmrp.io/ghchronicle/sinks/postgres/): The two ways into PostgreSQL, INSERT statements you pipe into psql and a sink that connects, the schema both declare, and why the conflict clause updates rather than does nothing. - [Graphite](https://docs.jmrp.io/ghchronicle/sinks/graphite/): Sending GitHub metrics to Graphite: the plaintext protocol over TCP, and the exact metric path, which is the dashboard's contract. - [Elasticsearch](https://docs.jmrp.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://docs.jmrp.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://docs.jmrp.io/ghchronicle/sinks/telegraf/): Sending GitHub metrics through Telegraf: line protocol posted to http_listener_v2, and the reason this is one sink instead of a hundred. - [File and stdout](https://docs.jmrp.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://docs.jmrp.io/ghchronicle/dashboards/): Five generated Grafana dashboards for GitHub metrics, one per store, and how to import each of them. - [What they show](https://docs.jmrp.io/ghchronicle/dashboards/panels/): The seventeen sections and their one hundred and fifty four panels, one capture each, and what changes when the store cannot answer. ## The card - [Overview](https://docs.jmrp.io/ghchronicle/card/): The ghchronicle card: a self-contained SVG of GitHub activity for a profile README, drawn from the same points the databases receive. - [Layouts](https://docs.jmrp.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://docs.jmrp.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://docs.jmrp.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://docs.jmrp.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://docs.jmrp.io/ghchronicle/reference/cli/): The ghchronicle command line: the flags, what each one does, and which of them print something and exit. - [Troubleshooting](https://docs.jmrp.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. - [Release history](https://docs.jmrp.io/ghchronicle/reference/changelog/): The current ghchronicle release and its date, read at build from VERSION and CHANGELOG.md, what that file records, and where every release is published. ## Other languages - [Spanish documentation index](https://docs.jmrp.io/ghchronicle/es/llms.txt): the same documentation in Spanish, page for page ## Optional Skip this section when context is short; nothing above depends on it. Its pages serve somebody driving ghchronicle from another program or changing its code, and the full documentation repeats every page of this index in one file. - [Calling it from a program](https://docs.jmrp.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. - [The test layers](https://docs.jmrp.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. - [Full documentation](https://docs.jmrp.io/ghchronicle/llms-full.txt) (799 KB): every English page concatenated, in the order of this index