Repository navigation
docs: correct what the first release tag made false - #209
Merged
Merged
Conversation
Cutting v1.3.0 falsified a cluster of claims at once, because they were all
conditioned on a tag that had never been cut. The images exist now, and are
verified to pull: both ghcr manifests answer 200 at :v1.3.0 and :latest.
docs/gpu-injection.md "No published container image ... there is no
registry image to name in a pod spec yet"
examples/README.md "no shim image is published", and the GPU shim
"cannot yet load into the images" (#121, closed)
examples/kubernetes/ "does not exist until a v* tag is pushed" (#139)
The collector bullet was false for a different reason: it said the DaemonSet
shape "is not built yet" and listed as open the questions #147 and #148
answered. #124 is closed, -mode=collector exists, and there is a daemonset
manifest. Replaced with the limit that is actually still there -- the
application pod still declares the volume and CUDA_INJECTION64_PATH, because
a hostPath shim changes which inode that names rather than removing the
variable.
A new docs/container-images.md, because the gap was not only stale text.
Nothing showed how to USE the images outside Kubernetes. The one container
example mounted the shim from /opt/perf-agent, a path that assumes you built
it. It now takes the library out of the image that ships it, and the agent
side is documented with the four capabilities, the bounding-set failure that
reports EPERM naming nothing, and why --pid=host is a real privilege
increase. Derived from the daemonset manifest rather than invented.
ALMOST GOT ONE WRONG IN THE OTHER DIRECTION. --symbol-fail-closed looked
wired: main.go parses it, WithSymbolFailClosed sets Config.SymbolFailClosed,
and agent.go passes it through as Options.FailClosed. But nothing in
symbolize/ ever reads that field, so the doc saying the semantics are not
wired was right, and rewriting the table row to describe a behaviour would
have replaced a true statement with a false one. The row now says precisely
where the flag reaches and that nothing reads it there.
Left alone because they are still true: the module-retention bullet
(module_retained_unattached is still in cupti_adapter.cc), bench's csv
output (the code prints "not implemented in v1"), and the debuginfod
metrics-exporter gap -- that one gained a clause, since the counters are
printed at shutdown now even though no exporter carries them.
dpsoft
added a commit
that referenced
this pull request
Oct 18, 2026
…210) Two unrelated things a reader notices and a writer does not. ISSUE NUMBERS. The user docs cited eight issues; six were closed, so clicking one landed on resolved work explaining nothing the paragraph had not already said. Citing an issue is useful when the reader can act on it — an open limitation they might hit — and is archaeology otherwise. The closed ones are gone from docs/, examples/ and the README; #194 stays in both places it appears, because it is open and names a limit a reader will meet. The CHANGELOG keeps all of its references: that is the historical record, where the numbers belong. One of those was not archaeology but a live falsehood #209 missed. The examples table still read "Not runnable yet — see #121" for kubernetes/, while the prose three lines below already said the opposite. Fixing the prose and leaving the table is how a document ends up contradicting itself in the same screen. PARCAGPU. The injection pattern is theirs and we took it directly, so the credit stays — but it opened the section meant to explain OUR two deployments, and their name appeared three times before a reader learned how to use either of ours. That reads as a comparison piece rather than a how-to, and it buries the attribution in argument rather than stating it. It is now a short "Prior art" section of its own, before anything else: the pattern is theirs, we took it directly, this document is what we do inside it. The privilege comparison keeps every number it had and moves under a heading that says what it is for, at the end of the deployments section instead of interleaved with them. No claim changed. "Neither deployment is zero-touch", including the note that Parca is in the same position, stays exactly where it was.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Cutting v1.3.0 falsified a cluster of documentation claims at once, because
they were all conditioned on a tag that had never been cut.
Verified before rewriting anything: both ghcr manifests answer HTTP 200
at
:v1.3.0and:latest, forperf-agentandperf-agent-shim.Stale because the images now exist
docs/gpu-injection.mdexamples/README.mdexamples/kubernetes/README.mdv*tag is pushed" (#139)That last one was written correctly — "runnable from the first release tag
onward". The condition simply came true, so the block is flipped rather than
rewritten.
Stale for a different reason
docs/gpu-injection.mdsaid the collector (DaemonSet) shape "is not builtyet" and listed as open the questions #147 and #148 answered. #124 is
closed,
-mode=collectorexists (cmd/gpu-cuda-profile/main.go:162), andthere is a daemonset manifest in the repo.
Replaced with the limit that is still there: the application pod still
declares the volume mount and
CUDA_INJECTION64_PATH. AhostPathshimchanges which inode that variable names; it does not remove the variable.
The gap was not only stale text
Nothing showed how to use the images outside Kubernetes. The single
container example mounted the shim from
/opt/perf-agent/…— a path thatassumes you built it yourself, which is exactly what publishing the image was
supposed to stop requiring.
New
docs/container-images.mdcovers both: taking the library out of thecarrier image, and running the agent with the four capabilities it needs. It
is derived from
gpu-collector-daemonset.yamlrather than invented, and itexplains the failure that is otherwise opaque — the binary carries file
capabilities, so the kernel refuses to exec it with a bare
EPERMnamingneither the capability nor the setting, before any of the program's code
runs.
One I nearly got wrong in the other direction
--symbol-fail-closedlooked wired:main.goparses it,WithSymbolFailClosedsetsConfig.SymbolFailClosed, andagent.gopassesit through as
Options.FailClosed. I rewrote the table row to describe abehaviour — then checked, and nothing in
symbolize/ever reads thatfield. The doc saying the semantics are not wired was right, and my "fix"
would have replaced a true statement with a false one. The row now says
precisely where the flag reaches and that nothing reads it there.
Checked and deliberately left alone
module_retained_unattachedis still incupti_adapter.cc:1959csv output is not implemented in v1the counters are printed at shutdown now (profile: system-wide symbolization takes ~107s for 148 samples on a machine with large Go binaries running #109), just not through an
exporter
Every link in the touched files resolves.