Skip to content
bucker

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

  1. Propose. Name a recipe and its typed slots (below), the finding it answers, and why. POST /orgs/:org/projects/:project/instrumentation-patches or the MCP tool instrumentation_patch_propose. A request that carries a diff, a file or a branch is refused: the body is a recipe and slots, never code.
  2. 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.
  3. Ask. pr.propose on the project is SENSITIVE and 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.
  4. 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.
  5. Merge. A person reviews and merges. Bucker has no merge operation.
  6. Watch. Seven days after the merge the finding is re-checked; verifiedAt (or revertedAt, 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 .env file, a key file, an agent instruction file, or anything outside the service root you named;
  • does not parse (JSON, YAML, .env and .conf grammar; 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's agentPrCreationEnabled switch.
  • The approver holds fix:approve and is a person outside the proposing session's delegation chain.
  • A policy that allows the proposal outright (or review mode) records the patch as proposed and opens nothing: a pull request is opened only for a patch a person approved, with the approval spent on this diff digest. Such a proposed patch does not count as "open": a later proposal of the same recipe that a person approves is planned beside it. Keep pr.propose at 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.