1"""The runner footprint: the runner-minutes the metrics window holds, by runner label.
3What ``fm ci.footprint`` prints. Each row of the ``metrics`` series
4([livery.workshop._metrics.SERIES][]) is one run with the forge's wall
5time of every job. A job whose display name lists its matrix, ``check
6(macos-latest, 3.14)`` or ``check (windows-latest, 3.14, 2of4)``, ran
7on the runner the first item names; every other job (the gate job, the
8docs build, the release jobs, the matrix picker) ran on the first
9runner ``[ci] runners`` names, where the workflow places them. The
10folded row of a platform's shards is left out: the forge never ran it,
11and the shards' own rows carry the minutes. A job without a wall time,
12still running when the gate job collected or never started, is counted
13apart and priced as nothing.
15The price is GitHub's, for the standard runners of a private
16repository; `fm ci.footprint` decides when to print it. A public
17repository on GitHub is not billed for them, so the price says what
18the same minutes would cost a private one.
19"""
33#: GitHub's rates in USD per minute for the standard runners of a
34#: private repository, by the class a runner label names: Linux
35#: 2-core, Windows 2-core, macOS 4-core (M1), as the page
36#: https://docs.github.com/en/billing/reference/actions-runner-pricing
37#: lists them. Larger runners cost more per minute and are not priced
38#: here; a public repository is not billed for standard runners at all.
41#: The page the rates come from, printed under the price.
44#: The two kinds a line sums: the check matrix's legs, and every other job.
48#: A matrix job's display name: the job, then its runner first inside
49#: the parentheses, then at least one more item (the Python, a shard).
55 """The jobs and minutes of one kind on one runner label.
57 Attributes:
58 label: The runner label, ``macos-latest``.
59 kind: `LEGS` for the check matrix's legs, `OTHER` for every
60 other job, counted on the first runner ``[ci] runners``
61 names.
62 jobs: How many jobs with a wall time the line sums.
63 minutes: Their summed wall time in minutes.
64 """
73 """The class the label names, a key of `RATES`; empty for none."""
74 return runner_class(self.label)
78 """The line's minutes at the class's rate; None for a label of no class."""
79 rate = RATES.get(self.runner_class)
80 return None if rate is None else self.minutes * rate
85 """The runner-minutes of a window of runs, by runner label and kind.
87 Attributes:
88 runs: How many runs the window holds.
89 first_day: The day of the oldest run, ISO; empty when no run
90 says when it was created.
91 last_day: The day of the newest run, ISO; empty likewise.
92 span_days: The days from the oldest run to the newest, at
93 least one: the rate per 30 days divides by it.
94 lines: One per runner label and kind, by label then kind.
95 untimed: The jobs without a wall time, counted apart.
96 """
107 """Every job the window holds, the ones without a wall time included."""
108 return sum(line.jobs for line in self.lines) + self.untimed
112 """The summed runner-minutes."""
113 return sum(line.minutes for line in self.lines)
117 """The priced lines' USD; a label of no class adds nothing."""
118 return sum(line.usd or 0.0 for line in self.lines)
122 """The lines whose label names no class."""
123 return tuple(line for line in self.lines if line.usd is None)
126 """*value*, a total over the window, as a rate per 30 days."""
127 return value * 30.0 / self.span_days
131 """The class *label* names: ``linux``, ``windows``, ``macos``, or empty.
133 By substring of the lowercased label: ``ubuntu`` or ``linux`` is
134 linux, ``windows`` is windows, ``macos`` is macos. A label naming
135 none, a self-hosted runner's say, is empty, and prices as nothing.
136 """
137 lowered = label.lower()
138 if "ubuntu" in lowered or "linux" in lowered:
139 return "linux"
140 if "windows" in lowered:
141 return "windows"
142 if "macos" in lowered:
143 return "macos"
144 return ""
148 """The runner label the job *display* ran on, and the kind of line it counts in.
150 A matrix job, ``check (macos-latest, 3.14)`` or ``check
151 (windows-latest, 3.14, 2of4)``, ran on the first item in its
152 parentheses and counts as `LEGS`. Every other display name ran on
153 *default* and counts as `OTHER`.
154 """
155 matched = _MATRIX.match(display)
156 if matched is None:
157 return default, OTHER
158 return matched["runner"].strip(), LEGS
162 """Whether *row* is a fold's own row: its ``shard`` lists the shards."""
163 shard = row.get("shard")
164 return isinstance(shard, Mapping) and "shards" in shard
168 stamp = str(entry.get("created_at") or entry.get("when") or "")
169 if not stamp:169 ↛ 170line 169 didn't jump to line 170 because the condition on line 169 was never true
170 return None
171 try:
172 return datetime.fromisoformat(stamp.replace("Z", "+00:00"))
173 except ValueError:
174 return None
178 entries: Sequence[Mapping[str, Any]], *, default_runner: str
179) -> Footprint:
180 """Sum the runner-minutes of *entries*, the rows of a window of runs.
182 Every job of every row is counted on one runner label, as
183 `runner_of` attributes it with *default_runner*; a fold's own row
184 is left out, since the shards' rows carry its minutes. A job whose
185 ``wall_ms`` is no number is counted apart. The span is from the
186 oldest row's creation to the newest, at least one day; a row that
187 says no moment is left out of it.
188 """
189 jobs: dict[tuple[str, str], int] = defaultdict(int)
190 minutes: dict[tuple[str, str], float] = defaultdict(float)
191 untimed = 0
192 for entry in entries:
193 rows = entry.get("jobs")
194 if not isinstance(rows, Mapping):194 ↛ 195line 194 didn't jump to line 195 because the condition on line 194 was never true
195 continue
196 for display, row in rows.items():
197 if not isinstance(row, Mapping) or _folded(row):
198 continue
199 wall = row.get("wall_ms")
200 if not isinstance(wall, int | float):
201 untimed += 1
202 continue
203 key = runner_of(str(display), default=default_runner)
204 jobs[key] += 1
205 minutes[key] += float(wall) / 60_000.0
206 moments = sorted(m for m in (_moment(entry) for entry in entries) if m is not None)
207 first, last = (moments[0], moments[-1]) if moments else (None, None)
208 span = (last - first).total_seconds() / 86_400.0 if first and last else 0.0
209 return Footprint(
210 runs=len(entries),
211 first_day=first.date().isoformat() if first else "",
212 last_day=last.date().isoformat() if last else "",
213 span_days=max(1.0, span),
214 lines=tuple(
215 Line(label, kind, jobs[label, kind], minutes[label, kind])
216 for label, kind in sorted(jobs)
217 ),
218 untimed=untimed,
219 )
223 """The first runner the root contract's ``[ci] runners`` names.
225 ``ubuntu-latest`` when the contract names none, as the workflow
226 renders it.
227 """
228 ci = load_contract(root / "workshop.toml").get("ci") or {}
229 runners = [str(runner) for runner in ci.get("runners") or ["ubuntu-latest"]]
230 return runners[0]
234 """The footprint as ``fm ci.footprint`` prints it: the window, a table, the rate.
236 The window line gives the runs, the days and the span. One table
237 line per runner label and kind, the total, and a line for the
238 jobs without a wall time when there are any. Then the minutes per
239 30 days from the span.
240 """
241 days = (
242 f", {summed.first_day} to {summed.last_day}"
243 if summed.first_day and summed.last_day
244 else ""
245 )
246 lines = [
247 f" {summed.runs} run(s) in the window{days}, {summed.span_days:.1f} day(s);"
248 f" {summed.jobs} job(s)",
249 f" a job outside the check matrix is counted on {default_runner}, the first"
250 " of [ci] runners, where the workflow places it",
251 f" {'label':<24} {'kind':<12} {'jobs':>6} {'minutes':>9}",
252 ]
253 lines.extend(
254 f" {line.label:<24} {line.kind:<12} {line.jobs:>6} {line.minutes:>9.1f}"
255 for line in summed.lines
256 )
257 timed = summed.jobs - summed.untimed
258 lines.append(f" {'total':<24} {'':<12} {timed:>6} {summed.minutes:>9.1f}")
259 if summed.untimed:
260 lines.append(
261 f" {'no wall time':<24} {'':<12} {summed.untimed:>6} {'-':>9} still"
262 " running when the gate job collected, or never started"
263 )
264 lines.append(
265 f" rate: {summed.per_30_days(summed.minutes):.0f} minutes per 30 days"
266 )
267 return lines
271 """The footprint priced at GitHub's rates for a private repository, as printed.
273 Only for a public repository on GitHub, which is not billed for
274 standard runners: the table says what the same minutes would cost
275 a private one, one line per runner label and kind at its class's
276 rate, a label of no class named as unpriced, then the total, the
277 USD per 30 days, and the source page.
278 """
279 lines = [
280 " a public repository on GitHub is not billed for standard runners; the"
281 " same minutes on a private one, at GitHub's rates:",
282 f" {'label':<24} {'kind':<12} {'class':<8} {'USD/min':>8} {'USD':>9}",
283 ]
284 for line in summed.lines:
285 usd = line.usd
286 if usd is None:
287 lines.append(
288 f" {line.label:<24} {line.kind:<12} unpriced: the label names no"
289 " class (ubuntu or linux, windows, macos)"
290 )
291 continue
292 lines.append(
293 f" {line.label:<24} {line.kind:<12} {line.runner_class:<8}"
294 f" {RATES[line.runner_class]:>8.3f} {usd:>9.2f}"
295 )
296 lines.append(f" {'total':<24} {'':<12} {'':<8} {'':>8} {summed.usd:>9.2f}")
297 lines.append(
298 f" rate: {summed.per_30_days(summed.usd):.2f} USD per 30 days; larger"
299 " runners cost more per minute"
300 )
301 lines.append(f" source: {SOURCE}")
302 return lines