Instrumentation patches
An instrumentation patch is a pull request that fixes how a service is instrumented: installs the SDK, turns tracing on, lists the hosts that receive trace context, upgrades a stale SDK, documents the environment variables it reads, adds the OpenTelemetry configuration for a cluster or a host. It is proposed by a person or an agent, approved by a person as an exact plan, opened as a draft pull request, and merged by a person. Bucker never commits to a default branch and never merges.
It is the fix behind the findings on the SDK inventory (instrumentation_health_get): a silent SDK, one
below its floor, tracing that is off, a service that calls hosts nobody traces.
How a patch happens
- Propose. Name a recipe and its typed slots (below), the finding it answers, and why.
POST /orgs/:org/projects/:project/instrumentation-patchesor the MCP toolinstrumentation_patch_propose. A request that carries a diff, a file or a branch is refused: the body is a recipe and slots, never code. - Plan. Bucker reads the repository at its default branch's head, runs the recipe (a pure, versioned function) and renders the diff. The diff is validated before anyone is asked.
- Ask.
pr.proposeon the project isSENSITIVEand asks. The approver reads the recipe and its version, the files (an edit to a file Bucker did not write is marked), the finding, the diff excerpt, the base commit and the diff's digest. The approval is bound to that digest and to the base commit. - Apply. After a person approves, the retry records the patch and opens ONE draft pull request on a
bucker/instrumentation-<recipe>-<digest>branch. The diff is rendered again from the same base and must still have the approved digest. - Merge. A person reviews and merges. Bucker has no merge operation.
- Watch. Seven days after the merge the finding is re-checked;
verifiedAt(orrevertedAt, if a person reverted the merge) lands on the patch.
The patch moves through proposed (recorded, nobody has approved it, so nothing is delivered),
approved, opened, merged, verified, reverted or rejected (closed without a merge).
Recipes
Each recipe is versioned. The version is part of the digest, so an approval never survives a recipe change.
| Recipe | What it changes | Frameworks |
|---|---|---|
install |
the dependency, one init module that reads the DSN from the environment, .env.example names, one import line in the entry file you name |
node, nextjs, browser, python |
add_tracing |
tracesSampleRate on the existing init call |
node, nextjs, browser |
outbound_spans |
tracePropagationTargets (the listed hosts only) and outboundHttpSpans |
node, nextjs |
session_propagation |
the browser session id on requests that already carry traceparent |
browser, nextjs |
track_calls |
one module naming the product events a service may send | node, nextjs, browser |
code_origin |
codeOrigin on the init call |
node, nextjs |
sdk_upgrade |
a dependency range, to a version Bucker has published (a major bump only when asked) | node, nextjs, browser, python |
config_file |
the variable names the SDK reads, in .env.example, empty |
node, nextjs, browser, python |
drop_unused_entry |
one single-line import of an unused SDK entry point | node, nextjs, browser |
tunnel |
one first-party route that forwards browser envelopes | nextjs |
sqlcommenter |
one module holding the traceparent SQL comment option |
node, nextjs |
otel_operator_instrumentation |
one Kubernetes Instrumentation resource |
kubernetes |
otel_injector |
one injector configuration file | host |
obi |
one OBI configuration file | host, kubernetes |
tracking_plan and csp_policy are named by the plan and reserved: they belong to SDK-19 and SDK-26
and are refused, naming their owner.
The three configuration-only recipes
otel_operator_instrumentation, otel_injector and obi write upstream configuration into your
repository and execute nothing. They create YAML or .conf files only, delete nothing, and their diffs
are refused if they contain an install, a download, a shell, a cluster command or a preload. Bucker does
not ship an injector or a recorder of its own: you apply the file with your own tooling, after review.
Each is named as configuration-only on the plan the approver reads.
What every patch is held to
A patch is refused, before anyone is asked, when its diff:
- touches a path the recipe does not name, a lockfile, a CI or hook directory, a
.envfile, a key file, an agent instruction file, or anything outside the service root you named; - does not parse (JSON, YAML,
.envand.confgrammar; balanced brackets in source); - carries a secret-shaped value (a DSN, a key, a value on an environment line: only names are written);
- executes anything (
child_process,eval,subprocess, and for the configuration-only recipes any install or shell); - touches more than 20 files or 400 lines, or a file over 256 KiB.
It is also refused when the project maps no repository, consent lacks contents:read or
pull_requests:write, the project's automation policy stops before a pull request, another patch of the
same recipe is approved or opened for the repository, the framework cannot be told, or the SDK version is
not one Bucker published.
No slot holds code. Every slot is a closed charset or a number (a host name, an event name, a sample rate, a version) and a recipe writes it only as an escaped literal. That, not a scan, keeps a field lifted from telemetry out of your repository.
Who may do what
- Proposing is
propose_fix(fix:propose) on the project. An agent also needs the organization'sagentPrCreationEnabledswitch. - The approver holds
fix:approveand is a person outside the proposing session's delegation chain. - A policy that allows the proposal outright (or review mode) records the patch as
proposedand opens nothing: a pull request is opened only for a patch a person approved, with the approval spent on this diff digest. Such aproposedpatch does not count as "open": a later proposal of the same recipe that a person approves is planned beside it. Keeppr.proposeat ASK if you want recipe plans delivered. - A retry reuses the
bucker/...branch an earlier attempt pushed only when that branch is exactly one commit on the base carrying exactly the approved files; anything else on that name is refused for a person to clear, never presented under the approval. - Merging, and reverting a merge, are yours. Neither has a tool.
Slots from telemetry
A host or an event name an agent read in telemetry is runtime text. The plan says so
(provenance: runtime_text, with the slots), and when the proposing session was served the same text the
operation is untrusted_text: the act stays at the draft-pull-request level whatever autonomy was earned.
Earned autonomy (config_pr)
pr.propose on a project is laddered under the config_pr category. The ladder covers a recipe only when
its golden diff is byte-stable and an earlier merge of it closed its finding inside seven days, and
never when one was reverted inside fourteen. The plan shows the reading (ladder.covered and why). No
rung reaches merge.
REST
| Route | |
|---|---|
POST /orgs/:o/projects/:p/instrumentation-patches |
Propose. 202 with an approval request, then 200 on the retry with approvalRequestId. |
GET /orgs/:o/projects/:p/instrumentation-patches |
The project's patches with their state; filter by state, recipe. |
GET /orgs/:o/projects/:p/instrumentation-patches/:patchId |
One patch. |
POST /orgs/:o/projects/:p/instrumentation-patches/:patchId/deliver |
Open the pull request of an approved patch whose delivery failed. No second approval; nothing for a patch no person approved. |
A patch of another organization or project is the same 404 as one that does not exist.
MCP
instrumentation_patch_propose (sdk toolset, fix:propose). It answers PENDING_APPROVAL until a
person decided; the call that carries the approval applies the plan and opens the draft
(DRAFT_PR_OPENED), and the answer says merged: false. File paths, the repository, the diff excerpt and
the provider's URL are declared untrusted. instrumentation_health_get include: [recipes] (wired by the SDK-01 package) serves the
catalogue above, and include: [patches] the project's patches.
Adding or changing a recipe
A recipe is a pure function in domain/src/modules/instrumentation-patches/recipes/: typed inputs and the
files it asked to read in, a plan of edits out. Add a golden case under
api/test/instrumentation-patches/golden/<recipe>/<case>/ (see its README), bump the recipe's version
whenever its output changes, and read the diff of the golden files: that is the review.