koji-lag(1)

✨ koji-lag(1) ✨ — Sandogasa Manual

okay so bestie, welcome to koji-lag from the Sandogasa Manual section 1 💖 this one is a whole mood and also extremely useful, so grab a snack 🍓

---

💖 NAME 💖

koji-lag — Quantify Koji build queue lag and per-arch build-time drag

🌸 SYNOPSIS 🌸

koji-lag [-h|--help] [-V|--version] <subcommands>

🦋 DESCRIPTION 🦋

Quantify Koji build queue lag and per-arch build-time drag

Like, that's the whole vibe: it measures how long your builds sit in the queue and how much each architecture drags. Iconic, honestly.

---

⭐ OPTIONS ⭐

• -h, --help — Print help. Your girl tells you how she works 💅
• -V, --version — Print version. Receipts, but for software.

---

👑 COMMANDS 👑

🎀 koji-lag annotate 🎀

koji-lag annotate [--instance] [--annotations] [--min-samples]
[-v|--verbose] [-h|--help] <--events>

Report the mass rebuilds and architecture stalls in a store — like it's going through your events tree and writing little margin notes in glitter pen ✨

• --events <DIR> — Events tree to rewrite, as passed to events --out
• --instance <INSTANCE> [default: fedora] — Known Koji instance (cbs, fedora, stream)
• --annotations <FILE> — Extra annotations, beyond the ones built in
• --min-samples <MIN_SAMPLES> [default: 5] — Withhold stats below this sample count in the rewritten reports
• -v, --verbose — (turn the chatter up)
• -h, --help — Print help

---

🧚 koji-lag events 🧚

koji-lag events [--no-verify] [--instance] [--since] [--until]
[--schedule] [--annotations] [--min-samples] [--format] [-v|--verbose]
[-h|--help] <--store> <-o|--out>

• --store <FILE> — Store to read from
• --no-verify — Skip the check for days the store claims and does not hold. iykyk, sometimes you just wanna trust the vibe 🙈
• --instance <INSTANCE> [default: fedora] — Known Koji instance (cbs, fedora, stream)
• -o, --out <DIR> — Directory to write the events tree into
• --since <YYYY-MM-DD> — First day to consider (default: everything the store holds)
• --until <YYYY-MM-DD> — Last day to consider, inclusive
• --schedule <DIR> — Release schedule checkout, for announced dates.

One f-NN/Fedora.Schedule.xml per release. With it, a rebuild reports the dates it was announced for beside the ones it ran on, and every event names the release cycle it fell in. So it's giving planned vs. actual, and she will read you both 🫶

• --annotations <FILE> — Extra outage causes, merged with the built-in ones.

Same form as the tool's own data/outages.toml. An entry that matches no detected event is reported rather than ignored — no silent ghosting here 💀

• --min-samples <MIN_SAMPLES> [default: 5] — Withhold report stats below this sample count
• --format <FORM,...> — Output forms: text, json, csv (comma-separated or repeated)
• -v, --verbose — Name each event as it is written
• -h, --help — Print help (see a summary with -h)

---

🌈 koji-lag export 🌈

koji-lag export [--instance] [--since] [--until] [-h|--help] <--store>
<-o|--out>

Write a store's rows out as CSV, for analysis elsewhere — take the data, run, be free 🦋

• --store <FILE> — Store to read from
• --instance <INSTANCE> [default: fedora] — Known Koji instance (cbs, fedora, stream)
• -o, --out <DIR> — Directory to write the CSV files into
• --since <YYYY-MM-DD> — First day to export (default: everything the store holds)
• --until <YYYY-MM-DD> — Last day to export, inclusive
• -h, --help — Print help

---

🔥 koji-lag probe 🔥

koji-lag probe [--instance] [--hub-url] [--depth] [--timeout]
[--page-size] [--steps] [-v|--verbose] [-h|--help]

Time one listing page, to size a backfill before starting it — literally a vibe check on your hub before you commit 👑

• --instance <INSTANCE> [default: fedora] — Known Koji instance (cbs, fedora, stream)
• --hub-url <URL> — Koji hub XML-RPC URL (overrides --instance)
• --depth <DAYS,...> [default: 1,600] — Depths to time, in days before now (comma-separated).

Defaults to a recent page and one at twenty months, which is roughly where cost stops being negligible. (Twenty months = 600 days, and bestie, she picked that number on purpose.)

• --timeout <SECS> — Seconds a single hub request may take; 0 waits forever.

Defaults to $SANDOGASA_KOJI_TIMEOUT, else 600. Raise it for a deep window: a page that exceeds the bound is abandoned and the retry pays the hub cost again, so too low a value can stop a backfill progressing rather than merely slow it. probe says what the depth you are asking for actually costs. (Translation: don't set this too low or your backfill just dies mid-stride, no cap 😭)

• --page-size <PAGE_SIZE> [default: 4000] — Rows per page, as sync --page-size would ask for
• --steps <STEPS> [default: 3] — Pages to walk from each depth.

At least two, because the first page into a region nobody has asked about lately costs several times what the ones behind it do — seven minutes against 55s when January 2025 was collected — and both numbers are needed to size a backfill.

• -v, --verbose — Name each page as it is timed
• -h, --help — Print help (see a summary with -h)

---

💅 koji-lag report 💅

koji-lag report [--instance] [--since] [--until] [--arch] [--owner]
[--package] [--class] [--scratch] [--official] [--include-failed]
[--out] [--min-samples] [--json] [--format] [-h|--help] <--store>

Per-arch queue-wait / build-time / bottleneck report — this is the main character right here ✨

• --store <FILE> — Store to report from
• --instance <INSTANCE> [default: fedora] — Known Koji instance (cbs, fedora, stream), with --store
• --since <YYYY-MM-DD> — Only tasks completing on/after this date (UTC midnight)
• --until <YYYY-MM-DD> — Only tasks completing on/before this date (UTC midnight)
• --arch <ARCH,...> — Restrict to these arches (CSV or repeated)
• --owner <NAME,...> — Restrict to builds by these accounts (CSV or repeated).

The account exactly as Koji records it, which for a service is a long name: koschei/koschei-backend01.rdu3.fedoraproject.org rather than koschei. Answers "how did my own builds fare" without anybody having to publish a per-person report. (Yes, use the whole long name, the short one will not match, I'm so serious 🙏)

• --package <NAME,...> — Restrict to these source packages (CSV or repeated)
• --class <CLASS,...> — Restrict to these classes of build (CSV or repeated).

One of mass-rebuild, eln-sync, eln-fix, koschei, ci, service, hand-scratch, official. Restrict to mass-rebuild before comparing one period with another: an unrestricted window is mostly koschei, whose mix moves with whatever it retried. (So like, compare apples to apples or the numbers gaslight you 🍓)

• --scratch — Only scratch builds
• --official — Only official (non-scratch) builds
• --include-failed — Include FAILED tasks in build-time statistics
• --out <DIR> — Write report.txt and report.json into this directory.

Both forms in one pass, since a reader wants the table and a machine wants the fields, and running the report twice to get both would read the dataset twice. Without it the report goes to stdout, as text or as JSON with --json. (One pass, two formats, no double work — efficiency ate 💅)

• --min-samples <MIN_SAMPLES> [default: 5] — Withhold human-output stats below this sample count
• --json — Print JSON instead of tables: shorthand for --format json.

Every tool here takes --json, so it stays as the conventional way to ask, and means the same thing.

• --format <FORM,...> — Output forms: text, json, csv (comma-separated or repeated).

Writing to a directory defaults to text,json. csv is one file per table, because a CSV holds one table where the other two carry every table for the period together.

• -h, --help — Print help (see a summary with -h)

---

🫶 koji-lag reports 🫶

koji-lag reports [--no-verify] [--instance] [--since] [--until]
[--min-samples] [--force] [--format] [-v|--verbose] [-h|--help]
<--store> <--reports-root>

Write reports for every period the store covers — she does the whole run, you just sit there being proud 🥹

• --store <FILE> — Store to report from
• --no-verify — Skip the check for days the store claims and does not hold
• --instance <INSTANCE> [default: fedora] — Known Koji instance (cbs, fedora, stream)
• --reports-root <DIR> — Directory tree to write reports into
• --since <YYYY-MM-DD> — First day to consider (default: everything the store holds)
• --until <YYYY-MM-DD> — Last day to consider, inclusive
• --min-samples <MIN_SAMPLES> [default: 5] — Withhold report stats below this sample count
• --force — Re-render reports that already exist.

Off by default, so re-running after an interruption costs nothing; pass it after changing what a report says, or after a sync has filled in rows a period was missing.

• --format <FORM,...> — Output forms: text, json, csv (comma-separated or repeated).

Writing to a directory defaults to text,json. csv is one file per table, because a CSV holds one table where the other two carry every table for the period together.

• -v, --verbose — Print each period as it is considered
• -h, --help — Print help (see a summary with -h)

---

💜 koji-lag sync 💜

koji-lag sync [--instance] [--hub-url] [--since] [--until] [--days]
[--timeout] [--page-size] [--sleep-ms] [--duty-cycle] [--retries]
[-v|--verbose] [-h|--help] <--store>

Fetch whatever the store is missing for a window — she goes and gets the crumbs your store is missing 🧺

• --instance <INSTANCE> [default: fedora] — Known Koji instance (cbs, fedora, stream)
• --hub-url <URL> — Explicit hub URL (overrides --instance; https only) 🔒
• --since <YYYY-MM-DD> — Window start date (UTC midnight, inclusive)
• --until <YYYY-MM-DD> — Window end date, inclusive (default: the last complete UTC day — the running day is never included implicitly)
• --days <N> — Sync the last N complete UTC days
• --store <FILE> — Store to fill (created if absent)
• --timeout <SECS> — Seconds a single hub request may take; 0 waits forever.

Defaults to $SANDOGASA_KOJI_TIMEOUT, else 600. Raise it for a deep window: a page that exceeds the bound is abandoned and the retry pays the hub cost again, so too low a value can stop a backfill progressing rather than merely slow it. probe says what the depth you are asking for actually costs.

• --page-size <PAGE_SIZE> [default: 4000] — Tasks per listTasks page.

A page costs what it costs to find, not to send: at thirteen months' depth 1000 rows take 18s and 4000 take 21s. Fewer, larger pages therefore ask the hub for far fewer expensive seeks, and the duty cycle keeps our share of it the same either way.

• --sleep-ms <SLEEP_MS> [default: 500] — Minimum pause between hub requests, in milliseconds
• --duty-cycle <PERCENT> [default: 50] — Share of one connection to use, as a percentage.

Each pause is scaled to how long the last request took, so a hub under load is asked less often and a hub that speeds up is asked more. 50 means pause as long as the request took; 100 paces by --sleep-ms alone.

• --retries <RETRIES> [default: 3] — Retries per failed hub request
• -v, --verbose — Print progress to stderr

---

okay and that's where part 1 wraps, bestie — there's literally more coming, don't go anywhere 💖

• -h, --help — prints the help, bestie 💖 (and yeah, '-h' gives you the short summary version, so if you want the whole essay, don't be shy with the long flag 👑)

---

🌸 koji-lag verify 🌸

koji-lag verify [--instance] [-h|--help] <--store>

Okay so this one is the little snitch of the family and I love her for it 🕵️‍♀️💅 she goes through a whole store and checks for any days it claims to cover but lowkey does not actually hold. Like, promise vs. reality check. The vibe check of data integrity, if you will ✨

Heads up babes: if she finds even one of those fake-claimed days, she exits non-zero. Which is iconic, actually, because it means you can wire her straight into your pipeline and let her gate a publish for you 🚦 no cap, she will slam the door on a bad release 🫶

• --store <FILE> — the store you want checked, bestie 🎀 hand her the file and let her snoop
• --instance <INSTANCE> — the known Koji instance you're working with. Your options are cbs, fedora, and stream. Default? fedora 💖 (she just assumes Fedora unless you tell her otherwise, main character energy tbh)
• -h, --help — prints the help ✨ yep, same deal as always: '-h' gives the short summary, the long flags give you the whole story 📖

---

aaaand that's the whole page, bestie 🦋 go forth and let verify gate your publishes so you never ship a lie again 💀✨ mwah 🫶

this one's from the sandogasa fam, version 0.27.0, dated 2026-10-21 💅 it's the koji-lag(1) manual, in case the vibe check didn't already tell you 👑