livery.workshop._traces¶
livery.workshop._traces ¶
The legs' traces: what a run cost, kept where no sync brings it.
A profiled job leaves two records, and the workspace contract prices them
apart under [ci]. timing, on unless the contract says otherwise,
runs every entry of every job profiled: each check leg writes a Chrome
trace of every task, step and test it ran, and its timing row, kilobytes
that fm ci.timings, the speed marks and fm ci.balance read, comes from
that trace. profile, off unless asked, pushes the trace itself,
megabytes a leg that only fm ci.profile reads, to a namespace of its own,
outside the one refspec a sync mirrors. profile-window says how many
runs the pushed channel keeps, profile-into where an assembled file
lands, and profile-keep how many of those files stay there. A pushed
trace is the one a profiled run writes, so profile = true beside
timing = false refuses.
Off is zero cost rather than less. timing = false runs nothing
profiled, writes no row and pushes nothing. With profile off the trace
stays on the runner and goes with it, so a checkout pays nothing for traces
nobody asked for, and the gate reads none of them. The file is a Chrome
trace of that leg: every task, step and test it ran, and the wall-clock
origin of its own clock, so one leg's timeline can be laid beside another's.
The push is observational. A trace that is not there and a push origin refuses are each one printed line, and none of them decides a job.
livery.workshop._traces.assemble reads the other way: one trace for a whole run, built from the forge's own job times and whatever traces the channel holds. The forge is asked for the skeleton and nothing else, so nothing here knows a forge.
Classes:
| Name | Description |
|---|---|
Policy |
What the contract says about the legs' traces. |
Caused |
One run about a commit. |
Node |
One commit of a chain, and the runs about it. |
Walked |
A chain of runs as one timeline. |
Assembled |
One run as a timeline, and where that timeline's zero sits. |
Functions:
| Name | Description |
|---|---|
policy |
The contract's |
sweep |
Keep the newest keep assembled files under at; what went. |
this_leg |
The leg this process belongs to, as the job runner named it. |
push |
Put trace on this leg's ref of the run; the line to print. |
about |
Record the commit this run ran on when the forge files it elsewhere; the line. |
runs_about |
Every run about commit, and a line per thing worth saying. |
chain |
Every run about commit, and the runs of what its merge produced. |
assemble |
One trace of a whole run: its jobs, their steps, and the legs' traces. |
newest_run |
The forge's newest run for head_sha, or empty when it lists none. |
drop_run |
Put the run of git's head in this command's own drop box; the line. |
drop_chain |
Put the chain from commit in this command's own drop box; the line. |
write_chain |
Write the chain from commit where a person can open it; and the lines. |
write_run |
Write a run's assembled trace where a person can open it; and the lines. |
Attributes:
| Name | Type | Description |
|---|---|---|
TRACE_FILE |
|
|
JOB_FILE |
|
|
TIMING_KEY |
|
|
PROFILE_KEY |
|
|
WINDOW_KEY |
|
|
INTO_KEY |
|
|
KEEP_KEY |
|
|
TIMING_DEFAULT |
|
|
PROFILE_DEFAULT |
|
|
WINDOW_DEFAULT |
|
|
KEEP_DEFAULT |
|
|
INTO_DEFAULT |
|
|
TRACES |
|
|
ABOUT |
|
|
RUN_PID |
|
|
LEG_PIDS |
|
TRACES
module-attribute
¶
TRACES = git.Keyed('run', ('run', 'leg'), namespace=git.TRACE_NAMESPACE, holds_rows=False, keep=_kept_runs)
ABOUT
module-attribute
¶
ABOUT = git.Keyed('about', ('commit',), namespace=git.TRACE_NAMESPACE, stale_after=timedelta(days=90))
Policy
dataclass
¶
What the contract says about the legs' traces.
Attributes:
| Name | Type | Description |
|---|---|---|
timing |
bool
|
Whether every job runs its entries profiled. On, each check leg writes a trace of every task, step and test it ran, and its timing row is read from that trace. Off means zero cost: no entry runs profiled, nothing is written on a runner, no row, no push. |
profile |
bool
|
Whether a job pushes the trace it wrote to the trace
refs, for a run to be assembled from. Off, the trace stays
on the runner and goes with it, and the timing row is
unaffected. On needs |
window |
int
|
How many runs' traces the pushed channel keeps. This one governs what a later assembly can still read, so it decides how far back a chain can be built. |
into |
str
|
Where an assembled file lands, relative to the workspace root unless it is absolute. |
keep |
int
|
How many assembled files stay in that directory. This one governs this checkout's own disk and nothing else: the files here are output, never input, so sweeping them strands no chain. |
Caused
dataclass
¶
Node
dataclass
¶
Walked
dataclass
¶
A chain of runs as one timeline.
Attributes:
| Name | Type | Description |
|---|---|---|
events |
list[dict[str, Any]]
|
Every run's events on one clock, in epoch microseconds, which is what a drop box takes and what a file records its zero against. |
nodes |
tuple[Node, ...]
|
The commits walked, in order. |
lines |
list[str]
|
A line per thing worth saying about the walking. |
Assembled
dataclass
¶
One run as a timeline, and where that timeline's zero sits.
Attributes:
| Name | Type | Description |
|---|---|---|
events |
list[dict[str, Any]]
|
The trace's events, every stamp relative to |
origin |
float
|
That zero, in wall-clock microseconds, which is what lets another timeline be laid on this one. |
lines |
list[str]
|
A line per thing worth saying about the assembling. |
policy ¶
The contract's [ci] trace keys for root, and what it got wrong.
The contract's judge refuses a key of the wrong type. A count below zero or an empty path is named with what it must be, and the default stands for it.
Raises:
| Type | Description |
|---|---|
Failed
|
when |
Source code in packages/workshop/src/livery/workshop/_traces.py
sweep ¶
Keep the newest keep assembled files under at; what went.
Runs after each write, so a checkout that profiles often does not accumulate. Newest by modification time, because the name carries a run id or a commit and neither orders by age. A keep of zero keeps everything: the count is a ceiling, and no ceiling means no sweeping rather than sweeping all of it.
Every trace in the directory is a candidate, whichever writer made it. The directory belongs to the mechanism, so a new writer gets housekeeping and an ignore rule without either being taught about it; the cost is that a file put there by hand is swept like the rest, and a trace to keep belongs somewhere else.
Returns one line per file removed, for the caller to report beside whatever it wrote. A file that cannot be removed is named and the sweep goes on: this is housekeeping and never a verdict.
Source code in packages/workshop/src/livery/workshop/_traces.py
push ¶
push(root: Path, trace: Path, *, job: str = '', leg: str = '', run: RunContext | None = None) -> str
Put trace on this leg's ref of the run; the line to print.
job is the job's name as the forge lists it, written down beside the trace: it is what an assembler joins the leg to its job by, and a matrix job's forge name cannot be derived from the leg's label.
leg is that label. The job runner gives it to the entries it
spawns and pushes from its own process, which never had it in its
environment, so the caller that knows the label says it;
livery.workshop._traces.this_leg answers for a caller running
inside a leg, where the environment is the only source.
Empty when the contract asks for no pushed traces ([ci] profile,
off unless asked), so a workspace that wants none neither pushes nor
says anything. Every other answer is a line: a trace that was never
written, a leg nothing named, a run this is not, or origin's own
refusal.
Source code in packages/workshop/src/livery/workshop/_traces.py
about ¶
about(root: Path, *, run: RunContext | None = None) -> str
Record the commit this run ran on when the forge files it elsewhere; the line.
A push run and a pull request run are filed under the commit they ran on, so nothing needs writing down. A dispatched run is filed under the tip of the ref it was dispatched on, and another merge landing between the dispatch and the run moves that tip past the commit the dispatch named. Then the forge's listing for the commit the run is about does not hold it, and only the run itself knows.
Written whatever the contract says about traces. The record is one row, and more than the assembler reads it: the merge point asks livery.workshop._traces.runs_about for the wave of a squash the forge filed under a tip that moved on, so a workspace that keeps no trace still keeps this. Empty outside a run, and on every run whose own head is the commit it checked out, which is most of them. Every other answer is a line.
Source code in packages/workshop/src/livery/workshop/_traces.py
runs_about ¶
Every run about commit, and a line per thing worth saying.
Two sources in one answer. The forge's listing for the commit holds the push run, the pull request runs and every dispatched run it filed under it. Beside that, the runs that recorded themselves, because the forge filed them under a commit that had moved on. A run both sources name appears once, from the forge.
Source code in packages/workshop/src/livery/workshop/_traces.py
chain ¶
chain(root: Path, repo: Repository, commit: str, *, depth: int = 2, now: datetime | None = None) -> Walked
Every run about commit, and the runs of what its merge produced.
Three recorded facts and no guesses: what the forge lists for a commit, what a run wrote down about the commit it ran on, and the merge commit a pull request names. So a chain followed while it happens and one walked from the same commit weeks later are the same tree, which is the property this exists for.
A release is two commits and one hop. The branch commit carries the pull request's run; the merge commit carries the base's own run and the wave dispatched at it, which is filed under the base's tip and found through the commit it recorded rather than through a time.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
The workspace root, whose channel the traces are read from. |
required |
repo
|
Repository
|
The repository the runs belong to. |
required |
commit
|
str
|
Where the walk starts. |
required |
depth
|
int
|
How many merges to follow. Zero walks the one commit. |
2
|
now
|
datetime | None
|
The moment a job still running is measured to. |
None
|
Returns:
| Type | Description |
|---|---|
Walked
|
The events, the commits walked with the runs about each, and a |
Walked
|
line per thing worth saying. A commit with no run and no merge |
Walked
|
is a node with nothing under it, never a guess. |
Source code in packages/workshop/src/livery/workshop/_traces.py
assemble ¶
assemble(root: Path, repo: Repository, run_id: str, *, head_sha: str = '', clock: float | None = None, now: datetime | None = None) -> Assembled
One trace of a whole run: its jobs, their steps, and the legs' traces.
The forge answers the skeleton: every job with its status, its conclusion, its start and end, and its own steps. Each job is a track of the run's process, so jobs that ran at once read as the parallel work they were. Where the channel holds that job's trace, its events are laid on the run's clock through the origin the trace recorded, in process groups of their own: the alignment is what nests them, and it comes from two clocks that were written down independently rather than from the order anything arrived in.
A job with no trace keeps its slice and its steps. A job the forge gives no times at all, a skip, is an instant event carrying its conclusion, because a thing with no duration is an event and not a span. A job still running is a slice up to the moment of assembly.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
The workspace root, which the traces are read through. |
required |
repo
|
Repository
|
The repository whose run this is. |
required |
run_id
|
str
|
The forge's own id for the run. |
required |
head_sha
|
str
|
The commit the run checked, when the caller knows it. With it the run's own row is read too, so the wait before each job can be drawn; without it the jobs' own times are the whole skeleton. |
''
|
clock
|
float | None
|
The wall-clock moment, in microseconds, every stamp is
measured from. The run's own first moment by default, which
is a file that starts at zero; |
None
|
now
|
datetime | None
|
The moment a running job's slice ends; the present by default. |
None
|
Returns:
| Type | Description |
|---|---|
Assembled
|
The events, the wall-clock moment they are measured from, and a line |
Assembled
|
per thing worth saying. No events at all means the forge listed no |
Assembled
|
job for the run. |
Source code in packages/workshop/src/livery/workshop/_traces.py
565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 | |
newest_run ¶
newest_run(repo: Repository, head_sha: str) -> str
The forge's newest run for head_sha, or empty when it lists none.
drop_run ¶
drop_run(repo: Repository, root: Path, *, run_id: str = '') -> str
Put the run of git's head in this command's own drop box; the line.
For a verb that followed a run to its end. With a trace being kept, the run it watched goes into the same box its own children drop into, so one file holds the local command, the run it caused, every job of that run, and every leg's tasks and tests underneath. The stamps are the wall clock's, which is what a box takes, and this run's writer lays the whole thing on its own clock.
Empty when no trace is being kept, which is the ordinary case: the verb calls this whatever its line asked for and pays one environment read.
Never raises. A trace is something noticed about a run, so nothing here may change what the run decided: every failure, git's and the forge's alike, comes back as the line to print. A CI leg proved the point by running its own tests under a profile, where a rig with no repository turned a watched merge into a failure.
Source code in packages/workshop/src/livery/workshop/_traces.py
drop_chain ¶
drop_chain(repo: Repository, root: Path, *, commit: str = '', depth: int = 2) -> str
Put the chain from commit in this command's own drop box; the line.
For a verb that followed its work to the end of everything it caused: a release, whose pull request run, base run and wave are one story. The stamps are the wall clock's, which is what a box takes, and this box's writer lays the whole thing on its own clock.
HEAD by default. Empty when no trace is being kept, which is the
ordinary case, so the verb pays one environment read.
Never raises. A trace is something noticed about work that is already done, so nothing here may change what that work decided: every failure, git's and the forge's alike, comes back as the line to print.
Source code in packages/workshop/src/livery/workshop/_traces.py
write_chain ¶
write_chain(root: Path, repo: Repository, commit: str, *, depth: int = 2, into: Path | None = None) -> tuple[Path | None, list[str]]
Write the chain from commit where a person can open it; and the lines.
The same walk the release command drops into its own trace, asked
for from a commit instead. The directory is the contract's
[ci] profile-into unless the caller names another.
Source code in packages/workshop/src/livery/workshop/_traces.py
write_run ¶
write_run(root: Path, repo: Repository, *, run_id: str = '', head_sha: str = '', into: Path | None = None) -> tuple[Path | None, list[str]]
Write a run's assembled trace where a person can open it; and the lines.
For investigating a run that has already ended, which is what the traces
are kept for. Without a run_id the forge's newest run for head_sha is
the one. The directory is the contract's [ci] profile-into unless the
caller names another.