Draft: docs: split S16 Step 17 into two MRs, its plan corrections, and the S16 spec fixes those reviews surfaced

Splits the Step 17 half out of !1831, which stays the catcher for Step 14's plan and spec amendments. This MR is the same thing for Step 17: it carries Step 17's plan text and takes the amendments that come out of the Step 17 MRs' reviews. It goes for review once Step 17 has merged.

What changed

  • Splits Step 17 into 17-1 and 17-2 at the conflict surface, with a per-MR table naming each part's metrics, wide-event operations, call-site files, and what it needs from the part before. 17-2 takes the six files Steps 14 and 15 have open, so 17-1 emits at the proxy rather than inside the shared relay writer.
  • Records 17-1's label budgets and its two test files, and scopes Depends on and the acceptance list per part.
  • Records !1935 in the Step 17 Status row.
  • Corrects 17-1's Files cell: it edits remote_referrers.go, not remote_taglist.go, whose only two error writes go through the shared 500 writer that stays unrecorded by design. Adds docs/dev/observability.md, which 17-1 also edits.
  • Drops the Step 17 Note's claim that the catalog already carries every metric the spec declares against S16. It did not: upstream_responses_total was missing unsupported_content from its outcome set.
  • Renames the oci_remote_proxy wide event's status field from http_status to status in docs/specs/S16-container-remote.md, and in the prose that spells the same key. LabKit lists http_status in fields.Deprecated as an alias for the canonical status, and the shipped emitter writes fields.HTTPStatusCode. The spec was the side that owed the change.
  • Corrects the same false "already carries" claim where the spec repeats it.

From the 17-1 review

  • auth_discovery_writes_total's row said the challenge label holds the parser's verdict and named unreadable as the only route to a persisted none. A discovery response that is not a 401 parses as a bearer challenge and still takes the no-token arm, so bearer had a second reading the row denied: a row that persisted no auth_url counted as an upstream discovered to need a token. The row now says bearer labels only the write that persists one, and the prose names the non-401 shape.
  • token_exchange_duration_seconds's row read as though it covered every handshake. It samples one discovery-and-exchange attempt, a re-discovery takes a second observation, and a handshake that fails before the exchange moves nothing. The row says so.

Not in this MR

The Status preamble. Its row count and its list of which steps collapse to one row are Step 14's to change, so that paragraph stays on !1831. Once !1831 merges, this MR wants a follow-up adding Step 17 to that sentence.

Booking the challenge-discovery leg on a metric. 17-1's review named the hole — a handshake that fails before the exchange moves no oci_remote_* family at all — and closing it needs either a discovery value on the existing outcome label or a family of its own. Both change the label sets the Metrics table names, so neither is a wording fix. ## Follow-ups takes an entry only with a linked work item, and none is filed.

Merge order

Independent of !1831 except for that one paragraph. Nothing here depends on Step 14's plan text, and the two MRs' hunks do not overlap.

Edited by Radamanthus Batnag

Merge request reports

Loading
Loading