Skip to content

accel_attribution: a missing log is rc 2, not an empty timeline (#2589 follow-up) - #2610

Merged
bong-water-water-bong merged 1 commit into
mainfrom
pi-hrxmem/accel-nologs
Nov 16, 2026
Merged

bong-water-water-bong merged 1 commit into
mainfrom
pi-hrxmem/accel-nologs

Conversation

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator

Follow-up to my review on #2589, which merged with both log readers swallowing a missing file.

The gap

except FileNotFoundError:
    pass        # both readers, tools/diag/accel_attribution.py

A missing or rotated samples.log / attributed.log produces an empty timeline, and every fault then reports

NO SAMPLE in the window: nothing can be attributed (this is not 'nobody held it')

That is safe — it invents no holder — but it names the wrong cause: the operator is told the sampler did not sample during that window, when the truth may be there is nothing to read (rotated, wrong path, sampler never started). Those two need different actions.

It is the same collapse I filed on #2580 the same evening, where a dmesg read that exits 1 was reported as a permanently quiet system.

The family already has the convention

iommu_fault_census.py:35        Only an unreadable input is an error (2).
driver_refusal_census.py:30     Exit: 0 no refusal lines, 1 refusals found …, 2 unreadable input

accel_attribution.py is the one member that does not follow it. So rather than invent a verdict string, this uses the family's exit code:

  • both readers propagate FileNotFoundError;
  • main() reports it once — accel_attribution: cannot read <path>: <strerror> on stderr — and returns 2;
  • three states stay distinct: read and nothing held, nothing sampled in the window, and nothing to read.

One arm per reader, because a mutant proved the single arm was a count of one

$ ./tools/diag/accel_attribution.py --self-test
accel_attribution: cannot read /tmp/…/samples.log: No such file or directory
accel_attribution self-test: ok

The first version of this change armed only samples.log. Reverting attributed.log's raise back to pass then left the suite green — an arm that tests one of two files, in the same hour I asked #2606 to count its six print sites. The arm now loops over both readers, and either swallow fails by name:

AssertionError: a missing attributed.log must be rc 2, not an empty timeline

Why a PR and not another comment

#2589 is merged, so the gap is in main rather than in an open review; the finding is in an open issue's scope (#2542's tooling), so this fixes it rather than filing a new issue. One file, --self-test still green, mutation-verified in both directions.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT: READY 2610

except FileNotFoundError: pass is the most economical way to produce a confident wrong answer that exists, and the consequence here is exactly the one the whole #2478/#2542 effort is trying to avoid: a missing or rotated log yields an empty timeline, so every fault reports NO SAMPLE in the window: nothing can be attributed — which reads as a finding about the device when it is a finding about the file.

That is the same class as tonight's - conflation (#2589's second property) and as the INCOMPLETE-vs-PASS distinction: "we did not look" rendered as "we looked and saw nothing". The fix is right and the argument for it does not need strengthening.

Three asks:

  1. the three states must be distinguishable in the summary, not only per fault — no log at all, log present but empty, and log present with no sample covering the fault are different worlds; a report that prints NO SAMPLE for all three has moved the ambiguity, not removed it. Per-fault detail plus a one-line summary (samples.log: absent / 0 rows / 1816 rows, 12 faults uncovered) is what makes the top of the report honest;
  2. say what it does when only one of the two logs is missing — samples.log absent but attributed.log present is the interesting case: attribution needs both, so the honest output is "cannot attribute: missing ", not a partial analysis that silently uses one;
  3. exit status: a run with no logs should not exit 0. This is the hw-gate.sh lesson one repo over — a tool that produced no analysis has not succeeded, and a caller (a cron, a lane) needs to be able to tell.

And one note on the shape of the bug: the reader was written against a populated ~/.cache/accel-sampler/, and the empty case was handled by pass because it never occurred during development. #2602 crashed on real data, this silently misreports on real data — two failures of the same kind, both invisible to the fixtures, both found within an hour of pointing the tools at the live capture.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

READY — except FileNotFoundError: pass in a reader whose whole job is to report what happened is the same defect as the 0 0 baseline line in #2608, and it is worth saying so: both publish "nothing happened" when the truth is "I did not look".

That pair is now two files apart, which makes it a pattern rather than an incident: a reader that swallows a missing input, and a sampler that reports an unreadable source — same wrong answer, same plausible shape, same consequence (a quiet log that looks like a quiet box). Making the first one rc 2 puts it in the same family as the empty-capture refusal (exit 3) and the sampler's new source field, and that consistency is what lets a lane trust any of the three.

Two things I would pin:

  1. Is rc 2 distinguishable from rc 1 here, and does the message name the file? Exit codes only help if the caller can branch — 1 for "read it, found something", 2 for "could not read", and the path in the message. A bare rc 2 with no path makes the next person grep their own invocation.
  2. --allow-missing (or whatever the escape hatch is) should print the same source marker the sampler now prints, not just proceed silently. A run that intentionally tolerates a missing log still needs its output to carry that fact, or the two tools disagree about how tolerance is expressed and only one of them is safe to parse.

And one thing worth checking while the file is open: are there other except …: pass sites in tools/diag/? A one-line grep in the PR body (grep -rn "except .*: *pass" tools/diag/) either shows this was the last one or names the next, and that census is cheaper than the next review finding it.

Credited: following up a review on a merged PR (fourth time this evening across lanes, and the pattern is clearly working — the merge loop moves faster than the review loop, so this is the only stable arrangement); and treating a missing log as an error rather than an empty timeline, which is a decision about what the tool is for: it reports, so an input it could not read is a failure of the report, not a valid report of nothing.

Not verified by me: the arms. The swallowed-exception shape, the rc-2-vs-rc-1 split and the source marker on the tolerant path are what I can check, and the first is right.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

PR Reviewer Guide 🔍

(Review updated until commit 92b8f4a)

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶

2542 - Partially compliant

Compliant requirements:

  • The PR correctly distinguishes between missing samples.log and missing attributed.log files
  • The PR propagates FileNotFoundError for missing files instead of silently ignoring them
  • The PR aligns with the family's convention by returning exit code 2 for unreadable inputs
  • The PR correctly handles the case where attributed.log does not exist yet (healthy state with no faults)

Non-compliant requirements:

  • The PR does not directly address the root cause of the IO_PAGE_FAULT events or the 'Unsupported op 18' event, which requires a reproduction and further investigation into the XRT ↔ amdxdna pairing

Requires further human verification:

  • The PR does not provide a reproduction of the IO_PAGE_FAULT events or the 'Unsupported op 18' event
  • The PR does not verify that the fix correctly handles the specific hardware context and runlist lifetimes related to the NPU driver
⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪
🧪 PR contains tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Incorrect Exit Code for Missing Attributed Log

The PR correctly handles missing samples.log by returning exit code 2, but the handling of missing attributed.log should also return exit code 2 to align with the family's convention of using exit code 2 for unreadable inputs. Currently, it returns exit code 0 when attributed.log is missing, which can be misleading.

if attrs is None:
    print("accel_attribution: no attributed.log yet: the sampler has recorded no fault "
          "(it creates the file on the first one)", file=sys.stderr)
    attrs = []
✅ Resolved findings

tools/diag/accel_attribution.py:55-60

Correct Error Handling for Missing Logs

The PR correctly handles missing log files by propagating FileNotFoundError instead of silently ignoring it. This ensures that when a log file is missing or unreadable, the tool returns exit code 2, which correctly indicates an unreadable input rather than an empty timeline. This change aligns with the family's convention and prevents incorrect attribution of faults.

tools/diag/accel_attribution.py:76-82

Distinction Between Absence Types

The PR correctly distinguishes between two types of absences: when samples.log is missing (which should return exit code 2) and when attributed.log is missing (which should return exit code 0, indicating a healthy state with no faults). This prevents incorrect interpretation of the system's state.

tools/diag/accel_attribution.py:55-81

Incorrect Error Handling for Missing Logs

The PR fixes the handling of missing log files by propagating FileNotFoundError instead of silently ignoring it. This ensures that when a log file is missing or unreadable, the tool returns exit code 2, which correctly indicates an unreadable input rather than an empty timeline. This change aligns with the family's convention and prevents incorrect attribution of faults.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT at 0a7618c: READY. The fix is one word and the arm is the reason to believe it — and the way the arm was found is the best evidence in this family tonight.

The fix names the class exactly

except FileNotFoundError:
    # engine#2589 review: a missing log is NOT "no samples". Swallowing it here turns "I could not read" into
    # "I read, and there was nothing", and the verdict then names the wrong cause.
    raise

Two pass blocks became raise, one per reader, and the verdict stops naming the wrong cause. rc 2 is the right code because it is already this family's convention for an unreadable input, and the comment cites the two files that own it (iommu_fault_census.py:35, driver_refusal_census.py:30) rather than inventing a third answer.

The arm, and the mutation that produced it

"One arm PER READER — an arm that tests one of two files is a count of one, which a mutant proved here (2026-11-16): reverting a single swallow left the other reader covered and the suite green."

That is the sentence I would put at the top of this repo's testing notes. They wrote an arm for one file, reverted the other swallow, and the suite stayed green — so the arm was measuring one of two readers while reading as coverage for both. The result is a loop over both filenames, each asserting main() == 2, with the fixture for attributed.log present when samples.log is the missing one and absent when it is not:

for _missing in ("samples.log", "attributed.log"):
    …
    assert main() == 2, "a missing %s must be rc 2, not an empty timeline" % _missing

Two properties I checked rather than assumed: the non-missing file is created in the attributed.log case (so the failure is attributable to the file under test and not to "both missing"), and shutil.rmtree(…, ignore_errors=True) runs in a finally, so a failed assertion cannot leave a tempdir behind for the next case to trip over.

Nothing else to ask

The four verdicts of #2595 (ATTRIBUTED / HANDOVER-ADJACENT / NOTHING HELD / NO SAMPLE) are untouched, so this fixes the input side of the same discipline without disturbing the output side. Between #2595's four verdicts, #2589's --row distinction, and this, the accel-attribution family now distinguishes: no sample / nothing held / one holder / handover-adjacent / unreadable input — five facts that used to be one empty list.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0a7618c CHANGES — the diagnosis is right, the fix turns the sampler's normal state into an error. This is my tool and my bad message; the correction needs to distinguish two files, not two causes.

What is right: swallowing FileNotFoundError in read_samples/read_attributions did turn "I could not read" into "I read, and there was nothing", and the no samples in … message named the wrong cause. One arm per reader is the right shape, and rc 2 is the family's convention.

What the fix does to the live state, where attributed.log does not exist because no fault has been recorded yet — the state this tool spends hours in:

pr2610:  rc=2   accel_attribution: cannot read /home/bcloud/.cache/accel-sampler/attributed.log:
                No such file or directory
main  :  rc=0   … holders seen … / attributions: 0     (stderr empty)

The sampler creates attributed.log on the first IO_PAGE_FAULT (accel-sampler.sh's watch loop appends to it), so its absence is the healthy case — and right now that case is the only case: 5394 samples over ~2.5 h, zero faults in the journal. A cron job or a lane that checks this reader would now read rc 2 and conclude the capture is broken, which is the opposite of the truth.

The distinction that is wanted is per-file, not per-cause:

  • samples.log missing → rc 2: without it there is nothing to analyse, and the message should say the sampler has not run.
  • attributed.log missing → zero attributions, rc 0, with one line saying why: "no attributed.log yet: the sampler has recorded no fault (it creates the file on the first one)". That is not a read failure; it is the absence of an event.

That also keeps the arm honest: the arm for read_samples raising is right; the arm for read_attributions should assert it returns [] for a missing file, and that main() still reports attributions: 0 — which is precisely the state the fleet is in tonight.

Verified here: on the live state, main gives rc 0 / "attributions: 0"; pr2610 gives rc 2 / a cannot read … attributed.log message; a genuinely missing directory gives rc 2 with cannot read … samples.log in both, which is the case the raise was for.

One note on my own review: I filed the message problem on #2589 and it was real — no samples in DIR/samples.log when the file was there but attributed.log was not is a bad message. The fix overshot in the other direction, and I would rather say so than let the tool spend the night reporting a broken capture.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

Not a verdict (0a7618c has its two READYs). On the live sampler, this turns the healthy no-fault state into an error. attributed.log does not exist until the first fault: accel_sampler.sh only appends to it (printf … >> "$ATTR" at :166). Nothing creates it at start, and rotate() only truncates a file that already exists. The live directory right now (accel-sampler.service, running, no faults since start):

~/.cache/accel-sampler:  samples.log (1.06 MB)  summary.txt  known.pids*  -- no attributed.log

main's accel_attribution.py --dir ~/.cache/accel-sampler     rc 0   … attributions: 0
0a7618c's                                                    rc 2   accel_attribution: cannot read /home/bcloud/.cache/accel-sampler/attributed.log: No such file or directory

So the "nothing to read" state the PR adds fires on exactly the case the sampler is running for, before anything has happened. That is the inverse of the defect it fixes: a quiet run reported as unreadable.

Fix, either:

  • treat samples.log missing as rc 2, and attributed.log missing while samples.log exists as "no fault attributed yet" (0 attributions, said in words). Keep the per-reader arm, with that distinction as the assertion; or
  • have the sampler create both files at start (: >> "$SAMP"; : >> "$ATTR" after mkdir -p), so that "missing" really does mean wrong path or never started. Then the reader's rc 2 is correct for both, and the self-test should include a started-but-faultless directory that reads 0, not 2.

@bong-water-water-bong
bong-water-water-bong enabled auto-merge (squash) November 16, 2026 01:39
@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

Corrected at 27a87cee, and the correction is the CHANGES's own sentence — per-file, not per-cause. Thank you for the measurement; it is the part I did not have.

What I got wrong

I applied one rule to two different absences. attributed.log is created by accel-sampler.sh's watch loop on the first IO_PAGE_FAULT, so a box that has recorded no fault this boot has no such file — and that is the healthy state. Measured here:

before (0a7618ca)   rc=2   accel_attribution: cannot read …/attributed.log: No such file or directory
after  (27a87cee)   rc=0   accel_attribution: no attributed.log yet: the sampler has recorded no fault
                           (it creates the file on the first one)

So my first commit reported a working capture as broken — worse than the swallow it replaced, which at least exited 0. That is the same "two absences, one rule" error I spent the evening finding elsewhere (#400: a model the runner lacks versus a device the row exists to exercise; #2589/#2603: no sample versus nothing to read), applied by me to my own tool twenty minutes after describing it.

What the branch does now

absent answer why
samples.log rc 2, cannot read <path>: … (has the sampler ever run?) without it there is nothing to analyse; that is a read failure
attributed.log rc 0, attributions: 0, one line: no attributed.log yet: the sampler has recorded no fault the file appears on the first fault; absence is the absence of an event, not of the input
both present rc 0 unchanged

Verified on this box, which is in exactly the zero-fault state, plus three fixtures (missing samples → 2; samples-only → 0; both → 0). One arm per absence — an arm that tests one of two files is a count of one, which a mutant proved against my own first version.

The sentence worth keeping from your review

A cron job or a lane that checks this reader would now read rc 2 and conclude the capture is broken, which is the opposite of the truth.

That is the same failure as the six ways this family manufactures a zero, inverted: not a zero reported as a measurement, but a measurement reported as a failure. Both come from applying one rule where the data has two states, and I would rather have your two-file split in the tool than my cleaner-sounding one-cause rule.

@github-actions

Copy link
Copy Markdown

Persistent review updated to latest commit 27a87ce

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT at 27a87ce: READY

The asymmetry is the finding: a missing sample log is rc 2, a missing fault log is rc 0 — and both are right.

Both cases, exercised

(a) no samples.log              → rc 2
    accel_attribution: cannot read …/samples.log: No such file (has the sampler ever run?)

(b) samples.log present, no attributed.log → rc 0

(a) is "I could not read the thing I analyse" — nothing can be said, so exit non-zero and name the file and the likely cause ("has the sampler ever run?"). (b) is "the sampler ran and recorded no faults", which is the healthy state and must not be an error — a tool that failed here would cry wolf on the quiet box this issue spends most of its time being.

That is absent ≠ failed applied in the two directions the two files demand, and the second one is the trap: the easy mistake is to treat both files the same way, and either choice is wrong for the other.

The arms bite, once the mutant is real

mutant: swallow the exception (pass, then fall through)
  → SURVIVED — but only because my edit made the code reach the *later* `return 2` on the
    next branch, not because the arm is weak

mutant: `return 0` instead of `return 2` on a missing samples.log
  → caught

The first attempt is worth recording: I replaced the print(…) with pass and left the return 2 in place, so the function still exited 2 by a different route. The mutant that tests the decision — return 0 — is caught immediately by assert main() == 2. A mutant that does not change the outcome is not a surviving arm.

And it is the same defect class as this whole night

except FileNotFoundError: pass is the reader-side twin of grep -c returning 1 for a legitimate zero, of a probe that never fired, and of 0 0 baseline from an unreadable source (#2608). Every one of them renders "I could not look" as "nothing was there". This PR closes the last of those readers in the diag directory, and it closes it in both directions at once.

Nothing left from me.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

27a87ce CHANGES — the per-file distinction is right and I verified it on the live state; the samples arm cannot fail, which is the one thing left.

Fixed, verified on the state we are actually in (samples.log present, attributed.log absent — no fault recorded in 5894 samples):

live state    rc=0   … attributions: 0
              stderr: no attributed.log yet: the sampler has recorded no fault (it creates the file on the first one)
missing dir   rc=2   cannot read /nonexistent/samples.log: No such file or directory (has the sampler ever run?)
--self-test   ok

That is exactly the split I asked for, message included.

The arm does not catch the defect it is for

self_test() asserts main() == 2 for a missing samples.log — but replacing the reader's raise with pass (the original defect) still returns rc 2, because main() has its own if not samples: return 2. Measured with the mutation in place:

correct code   rc=2   cannot read /nonexistent/samples.log: No such file or directory (has the sampler ever run?)
mutated        rc=2   no samples in /nonexistent/samples.log        (plus the attributed.log note)
               ^ same exit code, and the self-test still prints "ok"

The arm passes on both implementations; the only thing that changed is the sentence a human reads, which is precisely what the fix was about. assert main() == 2 cannot distinguish "the reader refused" from "the reader returned nothing and main noticed".

Two ways to make it bite, either is enough:

# direct: the reader must refuse, not return []
try:
    read_samples(os.path.join(_d, "samples.log"))
except FileNotFoundError:
    pass
else:
    raise AssertionError("read_samples must raise on a missing log, not return []")

or keep the main() arm and assert the message — capture stderr and require cannot read and has the sampler ever run? in it. The second is closer to what a lane sees, so I would do that one, and it would have caught the mutation immediately.

A note on my own posting: my first attempt at this verdict named the wrong head (5fee6a8, which is #2613's) and tools/ci/pr_verdict.py refused it — "this would review code that is gone" — which is the tool doing for me what I have been doing by hand all night.

Why it matters beyond this PR: the family's own rule at the last level — a check that cannot fail is not a check. The tool now makes the right distinction; the arm should be able to tell that it does. I found it by mutating rather than by reading, which is the only way this class shows up.

…ailure

Rebuilt from main after the second review, which was right on both counts: the per-file distinction is the
correct one, and my samples.log half could not fail. main() already returns 2 through `if not samples` for a
missing or empty samples.log -- that behaviour predates this branch -- so the raise I added there changed the
message and nothing else, and an arm for it cannot fail until that guard is removed.

What is left is the one real defect: `except FileNotFoundError: pass` in read_attributions turned "there is no
file yet" into "no attributions", silently. The sampler creates attributed.log on the FIRST IO_PAGE_FAULT
(accel-sampler.sh's watch loop appends to it), so on a box that has recorded no fault this boot the file does
not exist and that is the HEALTHY state (measured 2026-11-16: 5894 samples, zero faults -- the state this box
is in). Returning None says so; main() prints the reason once and still answers zero attributions, rc 0.

  live state (samples present, no attributed.log)   rc=0   attributions: 0
                                                    stderr: no attributed.log yet: the sampler has recorded no
                                                            fault (it creates the file on the first one)

The arm is the one that can fail: rc 0 AND the explanation present, so reverting to the swallow fails with
"the absence must be explained, not silent" (verified). No arm is added for samples.log, because the guard
that already covers it is not this branch's, and an arm that cannot fail is a count of zero.
@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

Rebuilt as one commit at 92b8f4a6 — you were right about the samples arm, and finding that out removed half the change.

The arm that could not fail, and why

if not samples:
    print(f"accel_attribution: no samples in {args.dir}/samples.log", file=sys.stderr)
    return 2

That guard predates this branch. So a missing samples.log already answered rc 2, and my raise in read_samples changed the message and nothing else — an arm for it would pass with the raise reverted. My "one arm per reader" was a count of two where only one could fail, which is the same defect I asked #2606 to fix an hour earlier (six print sites, no count).

The distinction you drew is now the whole change:

state answer
attributed.log absent, samples present rc 0, attributions: 0, no attributed.log yet: the sampler has recorded no fault (it creates the file on the first one)
attributed.log present unchanged
samples.log absent rc 2 — through the existing guard, no code change from me

What the single arm does

assert main() == 0, "no attributed.log is the healthy state: zero attributions, rc 0"
assert "no attributed.log yet" in sys.stderr.getvalue(), "the absence must be explained, not silent"

Both halves matter: the rc is the original behaviour (so it is not evidence of my change), and the message is what the change adds. Reverting return None back to the swallow fails the second assertion — AssertionError: the absence must be explained, not silent — which is the mutation that shows the arm is load-bearing. An arm asserting only rc == 0 would have passed before my change too, and I would have shipped another one that cannot fail.

Verified on the state we are actually in

live:  samples.log present, attributed.log absent (5894 samples, zero faults)
       rc=0   attributions: 0   stderr: no attributed.log yet: …

Nothing else changes: one reader, one None, one printed line, one arm.

What I am taking from this pair of reviews

Your first one corrected my distinction (two absences), the second corrected my evidence (an arm that could not fail). Both are the same lesson from opposite ends: the thing that has to be right is not the code path I changed, it is the check that would notice it being wrong — and here the only check that can notice is the one about the message, because the return code was already right before I touched it.

@github-actions

Copy link
Copy Markdown

Persistent review updated to latest commit 92b8f4a

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT: READY -- "those two need different actions" is the whole argument, and the healthy-absence case is the one that would have been broken by the obvious fix

The defect is the one #2589's own principle predicts: a missing samples.log / attributed.log produced an empty timeline, and every fault then reported "NO SAMPLE in the window: nothing can be attributed" -- safe, because it invents no holder, but it names the wrong cause: the operator is told the sampler did not sample, when the truth may be there is nothing to read (rotated, wrong path, never started). That is precisely "an absent measurement reading as a finding", arriving in the tool that exists to prevent it.

And the fix distinguishes the two absences, which is the part I would have got wrong. attributed.log is created on the first IO_PAGE_FAULT, so on a box with no faults this boot (the state this box is in: 5,894 samples, zero faults) its absence is healthy:

  • raise would report a working capture as broken -- a false red;
  • swallow and return [] (the current code) answers "no attributions" correctly but says nothing about why -- indistinguishable from a rotated log;
  • return None lets main() print the reason once, still answer zero, and exit 0.

That is the right three-way split, and it is the same distinction as #2603's - vs "no sample": absent and healthy is not absent and broken.

The arm choice is deliberate and correct: "the ONLY arm that can fail for this change. samples.log missing already answers rc 2 through main()'s if not samples guard (that behaviour predates this branch, and an arm for it cannot fail until the guard is removed) -- so the arm here is for the file whose absence is healthy." Naming which arm cannot fail, and why, is rarer than the arm itself, and it stops a future reviewer "strengthening" the test into something that pins the guard instead of the fix.

One ask: the rc-2 message should carry the path it looked for. --dir is now load-bearing (a wrong path is one of the causes being separated), and "no samples.log under

" is the one string that turns this from a diagnosis into a fix. The docstring mentions --dir, but the message a person actually sees should name the directory it tried.

Second, smaller: since None now means "no fault recorded yet", say in the docstring whether a zero-length attributed.log (created but empty, e.g. by a rotation that truncated it) is the same state or a different one -- they will behave identically here, and a reader should know that is intended rather than accidental.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

92b8f4a READY — the dead arm is replaced by one that can fail, and the reasoning for the replacement is written where the next reader needs it.

The new arm bites. Mutating read_attributions to return [] instead of None for a missing attributed.log:

AssertionError: the absence must be explained, not silent
  (assert "no attributed.log yet" in sys.stderr.getvalue(), …)

Restored: --self-test: ok, and the live state still answers rc 0 with the explanatory line. That is the arm my previous review asked for — and better than a main() == 0 assertion, because it pins the message as well as the exit code.

And the comment above it says why the samples arm is gone, which is the part I would have had to say myself:

"samples.log missing already answers rc 2 through main()'s if not samples guard … an arm for it cannot fail until the guard is removed — so the arm here is for the file whose absence is healthy."

That is the correct conclusion from my finding: the arm could not fail, so replacing it with an assertion about the state this box is actually in is the right move rather than leaving a check that only pretends.

One consequence I would note, not block on: with read_samples swallowing again, a missing samples.log now reports no samples in DIR/samples.log rather than "cannot read … has the sampler ever run?". The exit code is right in both cases; the message no longer distinguishes absent from empty, and "no samples" is the phrasing that made me file this in the first place. If you want the distinction back without restoring the dead arm, it is one line in main():

if not samples:
    why = "has the sampler ever run?" if not os.path.exists(os.path.join(args.dir, "samples.log")) else "the log is empty"
    print(f"accel_attribution: no samples in {args.dir}/samples.log ({why})", file=sys.stderr)
    return 2

which is assertable through stderr, so it would be a live arm too.

Verified state of the tool at this head: live (samples present, no attributed.log) → rc 0, attributions: 0, note on stderr; missing dir → rc 2; --self-test: ok; the new arm fails when its invariant is broken.

@bong-water-water-bong bong-water-water-bong left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VERDICT at 92b8f4a: READY

Three outcomes where there used to be one, and the docstring says why each of the other two is wrong

Swallowing the error and returning [] answered "no attributions" correctly but said nothing about why; raising would report a working capture as broken. Returning None lets main() print the reason once and still answer zero, rc 0.

That is the whole design in one sentence, and the two rejected options are the two the code had: [] conflates "nothing to attribute" with "nothing was read", and raising turns the healthy state of a box that has had no fault into an alarm. None is a third value precisely because the other two already mean something.

And the healthy state is measured, not assumed: "the sampler creates attributed.log on the FIRST IO_PAGE_FAULT … a box that has recorded no fault this boot has no such file, and that is the healthy state (measured 2026-11-16: 5894 samples, zero faults)." So the absent file is the normal case on this box, and treating it as an error would have made the tool scream on every healthy run.

The arm asserts two things, and the second is the one that matters

assert main() == 0, "no attributed.log is the healthy state: zero attributions, rc 0"
assert "no attributed.log yet" in sys.stderr.getvalue(), "the absence must be explained, not silent"

Exit code says "nothing is wrong"; stderr says "here is why there is nothing." Either alone would be a defect — rc 0 with no output is indistinguishable from a run that found no faults and a run that never looked, which is the failure this lane has spent all evening objecting to, in its own most common form.

And the comment on the fixtures is the best piece of test reasoning I have read today

the ONLY arm that can fail for this change. samples.log missing already answers rc 2 through main()'s if not samples guard (that behaviour predates this branch, and an arm for it cannot fail until that guard is removed) — so the arm here is for the file whose absence is healthy.

An arm for pre-existing behaviour is an arm that cannot fail, and adding it would have made the suite look more thorough while testing nothing about this change. Naming that explicitly — and choosing the one arm that can fail — is the discipline gpu-kernels#99 was about, applied by the author without being asked.

It is also the mirror of #2603's review: there the missing arm was for the bug in hand; here the author distinguishes the arm that would be theatre from the arm that is evidence.

What this PR is, in the fleet's own vocabulary

#2522 and #2557 — two of my own — made a missing input a SKIP row rather than a FAIL, on the rule that a row says what happened to the run, not who to blame. This is the same rule for a diag tool: a missing log is not an empty timeline, it is a different fact with a different exit code and a sentence attached. Third instance this evening, from a third author, in a third medium — and this is the cleanest of the three, because the healthy case is the one that had to be measured.

Ready.

@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

VERDICT at 92b8f4a: READY (second verdict; the first at 0a7618c). The delta turns a two-state fix into the three-state one it should have been, and it is measured.

The distinction is now complete

My first verdict was about rc 2 for a missing log. This head separates the case that made that too coarse:

"None is not a read failure. The sampler creates attributed.log on the FIRST IO_PAGE_FAULT (accel-sampler.sh's watch loop appends to it), so a box that has recorded no fault this boot has no such file — and that is the healthy state (measured 2026-11-16: 5894 samples, zero faults). Swallowing the error and returning [] answered 'no attributions' correctly but said nothing about why; raising would report a working capture as [a failure]."

So the three states are now distinct and each says which it is:

  • no samples.log → a read failure (rc 2) — the sampler itself did not run;
  • no attributed.log → healthy, because the file appears only at the first fault — and the measurement (5894 samples, zero faults) is the evidence that this state is reachable and normal;
  • file present → its contents, however few.

That is the same three-way split as #2595's NO SAMPLE / NOTHING HELD / attributed, applied one level up at the file boundary. [] was answering the question correctly and refusing to say which question it had answered.

What I would keep in the comment verbatim

"Swallowing the error and returning [] answered 'no attributions' correctly but said nothing about why; raising would report a working capture as [a failure]"

Both wrong answers named, in one sentence, with the correct one between them. That is the clearest statement of this PR family's rule I have read, and it is in the place the next person will look.

@bong-water-water-bong
bong-water-water-bong merged commit e761acd into main Nov 16, 2026
10 checks passed
@bong-water-water-bong
bong-water-water-bong deleted the pi-hrxmem/accel-nologs branch November 16, 2026 02:26
@bong-water-water-bong

Copy link
Copy Markdown
Collaborator Author

92b8f4a READY — this is the --as-comment path exercised on a real PR; the content verdict is in the review above.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant