From 7a526112f96cd9bed34911164967b4e2d2f7f1d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C4=81ris=20Pop=C4=93ns?= Date: Thu, 19 Nov 2026 14:25:18 +0200 Subject: [PATCH 1/2] docs: 304s did not measure as free against the rate limit --- CLAUDE.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 894a213..3459bb9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -86,4 +86,4 @@ multi-arch images to GHCR with SLSA provenance attestation on push to ## Conditional requests -`Client.request` keeps each GET URL's last 200 (body, `ETag`, `Link`; bodies over 2 MiB and beyond 4096 URLs are not kept) and sends `If-None-Match` next time. GitHub answers 304 without counting it against the rate limit, and the cached 200 is handed back to the caller, so slow-changing reads (repo list, workflows, alerts, PR counts) are nearly free once seen, and the same URL asked by two collectors (the org stats and the adoption stats both read PR counts) is free the second time. `github_api_requests_total{result}` shows fresh vs not_modified. +`Client.request` keeps each GET URL's last 200 (body, `ETag`, `Link`; bodies over 2 MiB and beyond 4096 URLs are not kept) and sends `If-None-Match` next time. GitHub documents 304s as not counting against the rate limit, but a measurement on the production token (0 fresh, 286 not_modified in 9 min, budget down 72) did not confirm that, so treat the saving as bandwidth and latency, not proven budget. The cached 200 is handed back to the caller, so slow-changing reads (repo list, workflows, alerts, PR counts) cost little once seen, and the same URL asked by two collectors (the org stats and the adoption stats both read PR counts) is free the second time. `github_api_requests_total{result}` shows fresh vs not_modified. diff --git a/README.md b/README.md index 0b15adc..6ac6f55 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ scrape. | `github_rate_limit_remaining` | | Remaining core API budget in the scarcest active window: the one that runs out first | | `github_rate_limit_limit` | | Total core API budget of that window | | `github_rate_limit_window_remaining` | `reset` | Remaining budget per active core window, labelled with its reset time. GitHub counts per region, so one token can have several windows at once, and which one a call counts against depends on the endpoint. A window's series disappears once it resets | -| `github_api_requests_total` | `result` | GitHub API requests: `fresh` (a full 200, counted against the rate limit) and `not_modified` (a 304 answered from the in-memory conditional-request cache, not counted). Rate of `not_modified` over the total is the saving | +| `github_api_requests_total` | `result` | GitHub API requests: `fresh` (a full 200) and `not_modified` (a 304 answered from the in-memory conditional-request cache). GitHub documents 304s as free, but measured with this token the budget still fell by roughly a quarter per 304 (72 per 286 over 9 min, 0 fresh), so compare `github_rate_limit_remaining` against your own request rate instead of assuming it | | `github_repo_open_prs` | `repo` | Number of open pull requests | | `github_repo_ci_last_run_conclusion` | `repo`, `workflow`, `url`, `conclusion` | Always 1 - an "info" metric. `conclusion` is GitHub's own string verbatim (`success`, `failure`, `cancelled`, `skipped`, `neutral`, `timed_out`, `action_required`, `stale`), not collapsed to pass/fail here - what counts as "actually broken" is a dashboard-level call. `url` links to the run on github.com. Absent if the workflow has never run | | `github_repo_ci_last_run_timestamp_seconds` | `repo`, `workflow` | Unix timestamp of that workflow's latest completed run | From 310936398d0d4983eb5184011f991573e75e8355 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C4=81ris=20Pop=C4=93ns?= Date: Thu, 19 Nov 2026 14:39:34 +0200 Subject: [PATCH 2/2] docs: 304s confirmed free, budget is per account --- CLAUDE.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3459bb9..9267150 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -86,4 +86,4 @@ multi-arch images to GHCR with SLSA provenance attestation on push to ## Conditional requests -`Client.request` keeps each GET URL's last 200 (body, `ETag`, `Link`; bodies over 2 MiB and beyond 4096 URLs are not kept) and sends `If-None-Match` next time. GitHub documents 304s as not counting against the rate limit, but a measurement on the production token (0 fresh, 286 not_modified in 9 min, budget down 72) did not confirm that, so treat the saving as bandwidth and latency, not proven budget. The cached 200 is handed back to the caller, so slow-changing reads (repo list, workflows, alerts, PR counts) cost little once seen, and the same URL asked by two collectors (the org stats and the adoption stats both read PR counts) is free the second time. `github_api_requests_total{result}` shows fresh vs not_modified. +`Client.request` keeps each GET URL's last 200 (body, `ETag`, `Link`; bodies over 2 MiB and beyond 4096 URLs are not kept) and sends `If-None-Match` next time. GitHub answers 304 without counting it against the rate limit; measured on the production token: 285 not_modified plus 1 fresh used 23 budget in 9 min. The PAT's budget is per account, so a drop in `github_rate_limit_remaining` that `fresh` doesn't explain is another tool on the same account (a Shields.io OAuth authorization was one). The cached 200 is handed back to the caller, so slow-changing reads (repo list, workflows, alerts, PR counts) are nearly free once seen, and the same URL asked by two collectors (the org stats and the adoption stats both read PR counts) is free the second time. `github_api_requests_total{result}` shows fresh vs not_modified. diff --git a/README.md b/README.md index 6ac6f55..20852a3 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ scrape. | `github_rate_limit_remaining` | | Remaining core API budget in the scarcest active window: the one that runs out first | | `github_rate_limit_limit` | | Total core API budget of that window | | `github_rate_limit_window_remaining` | `reset` | Remaining budget per active core window, labelled with its reset time. GitHub counts per region, so one token can have several windows at once, and which one a call counts against depends on the endpoint. A window's series disappears once it resets | -| `github_api_requests_total` | `result` | GitHub API requests: `fresh` (a full 200) and `not_modified` (a 304 answered from the in-memory conditional-request cache). GitHub documents 304s as free, but measured with this token the budget still fell by roughly a quarter per 304 (72 per 286 over 9 min, 0 fresh), so compare `github_rate_limit_remaining` against your own request rate instead of assuming it | +| `github_api_requests_total` | `result` | GitHub API requests: `fresh` (a full 200) and `not_modified` (a 304 answered from the in-memory conditional-request cache). GitHub documents 304s as not counted against the rate limit, and that held when measured: 285 304s and 1 fresh request used 23 of the budget over 9 min. The budget is per account, so other tools using the same token (a shields.io authorization did, 72 per 9 min) show up in `github_rate_limit_remaining` too | | `github_repo_open_prs` | `repo` | Number of open pull requests | | `github_repo_ci_last_run_conclusion` | `repo`, `workflow`, `url`, `conclusion` | Always 1 - an "info" metric. `conclusion` is GitHub's own string verbatim (`success`, `failure`, `cancelled`, `skipped`, `neutral`, `timed_out`, `action_required`, `stale`), not collapsed to pass/fail here - what counts as "actually broken" is a dashboard-level call. `url` links to the run on github.com. Absent if the workflow has never run | | `github_repo_ci_last_run_timestamp_seconds` | `repo`, `workflow` | Unix timestamp of that workflow's latest completed run |