koji-lag - Man Page

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

Report the mass rebuilds and architecture stalls in a store

--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

-h, --help

Print help

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

--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.

--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.

--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 [--instance] [--since] [--until] [-h|--help] <--store> <-o|--out>

Write a store's rows out as CSV, for analysis elsewhere

--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 [--instance] [--hub-url] [--depth] [--timeout] [--page-size] [--steps] [-v|--verbose] [-h|--help]

Time one listing page, to size a backfill before starting it

--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.

--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]

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 [--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

--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.

--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.

--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.

--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 [--no-verify] [--instance] [--since] [--until] [--min-samples] [--force] [--format] [-v|--verbose] [-h|--help] <--store> <--reports-root>

Write reports for every period the store covers

--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 [--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

--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

-h, --help

Print help (see a summary with '-h')

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

Check a store for days it claims to cover and does not hold.

Exits non-zero when it finds one, so it can gate a publish.

--store <FILE>

Store to check

--instance <INSTANCE> [default: fedora]

Known Koji instance (cbs, fedora, stream)

-h, --help

Print help (see a summary with '-h')