Emit named measurement spans that the whole core shares

[iderex]

The four published numbers are met or missed inside this repository, which is why
the kickoff puts the instrumentation here. Instrumentation added per subsystem
gives four subsystems measuring four slightly different things, and the numbers
then cannot be added up.

What this produces

One measurement facility every subsystem uses, with named spans taken from the
record in #8 so the names are decided once.

A monotonic clock that a test can control, so that a timing test takes
microseconds and produces the same answer on a loaded machine as on an idle one.

A cost near zero when nobody is listening, since instrumentation that slows the
thing it measures reports on itself.

Spans that a client can subscribe to, because the whole numbers need the client's
half and it cannot supply it without knowing when the core's half ended.

Done when

Every span named in #8 is emitted by the code that owns it, the suite drives
them through a controlled clock, and a test proves the overhead with no
subscriber is below a stated bound. Blocked on #8, #9, and #102, which decides
the clock a span is measured against and what the controlled clock in the suite
is allowed to move.

[iderex]

The clock this issue was waiting on is decided in docs/decisions/0102-the-clocks-every-deadline-is-measured-against.md.

The interval a span reports is on the steady clock, and the record names this issue in the row that says so. A span is a duration inside one run, and a wall-clock correction part way through one would otherwise produce a negative interval, which is the reading nobody goes looking for and the one that gets investigated longest.

The elapsed clock is the wrong one here. A span that covered a suspension would report the sleep as time the core spent, and the numbers in #8 are about what the core spent rather than how long a device was away.

What the controlled clock in the suite may do is fixed in the same record, and it is the part this issue needs before a timing test can be written. A test may set and move the wall clock freely, in both directions and by any amount. It may advance the steady and the elapsed clock by any amount and independently of each other, which is how a suspension is expressed. It may not move either monotonic clock backwards, the fake source refuses that rather than allowing it, and the refusal is itself tested, because the shipping code has no branch for a monotonic clock going backwards and a suite able to move one would be proving behaviour that nothing ships.

All three clocks reach the core through one injected source, and nothing in the core reads a platform clock directly. That is what makes a timing test take microseconds and give the same answer on a loaded machine as on an idle one, which is what this issue asks of the controlled clock.

[iderex]

The facility landed as docs/decisions/0061-the-span-facility.md, on c1ce0e1. The clock is settled in the comment above and the record reads it rather than restating it.

What was left here was a seam three landed records name and none of them specifies. 0100 defers the facility itself, its names, its subscription and its measured overhead to this issue by name. 0008 names the three intervals a build is gated on, the six sub-intervals inside them, and the identifier a client's own half joins to. 0102 names the clock. Following any of the three arrives here and finds the name with nothing behind it.

A span carries a name, an identifier, a parent, an interval read from the single injected steady source, and an outcome from three values: completed, failed, cancelled. Three rather than two because 0009 already separates a cancelled call from every failure and #37 maps nothing onto it, and because the wall of two hundred tiles in #53 is where most spans are withdrawn, so two values would spoil the ordinary case rather than an unusual one. A failed span carries no kind from 0004, since the kind is already on the failure the caller received and on the event 0100 emits for it.

Four things in it were not on this issue's list, and each of them refuses a cheaper shape that nothing would report as wrong.

The parent is handed over where a span is opened, never inferred from an ambient context. 0009 moves work between two lanes by design, a body large enough to matter is parsed on the other one from the request that fetched it, and a completion may run in a sink the client supplied. A context that is not carried across one of those handovers is wrong at exactly the handovers the sub-intervals exist to measure, and the result is sub-intervals that add up to the wrong thing with nothing in the number saying so.

The identifier comes from a counter the core owns rather than from a space wide enough to be unique across devices and runs. 0008 needs it only to pair a client's half with a core interval inside one run, and that is the whole of what it is for. A globally unique one is stable enough to correlate two reports from one device, which 0068 places outside what the core hands anybody, and it is the one choice here that cannot be repaired afterwards: narrowing it later does not reach what a client has already sent.

A span carries no fields at all. Not an item identifier, not a server address, not a byte count. 0068 places an item identifier under its personal data list and 0100 shapes an event as fields rather than a sentence so that #71 can redact by reading field names, and a facility with no fields does not need that rule to reach it. What is given up is attribution: a span says an artwork decode inside a cold first tile took what it took and does not say which image, which is the right trade for arithmetic over many intervals and the wrong one for looking into a single occurrence, which is what an event is for.

The decision about whether anybody is listening is taken at open rather than at close. The natural implementation opens the span, reads the clock, and decides at close whether to hand anything over; it is close to free in the ordinary sense and it still reads a clock twice per span, six sub-intervals deep, across two hundred tiles. Because the subscriber is supplied where the core is created and not changed afterwards, the answer at open is the answer at close, so there is no span opened without a reading and closed with one.

Names are the last piece and the record deliberately does not enumerate them. It fixes the rule, which is lower case, dotted, and a sub-interval's name beginning with the name of the interval it sits inside, and it requires every name to be declared in one place in the tree rather than written as a literal where it is emitted, so #67 has a set a run can print. Which subsystem emits which sub-interval belongs to the issue that builds it, which is where 0100 already places the identity of an event. Adding a name is therefore not a change to the record; renaming one of the three in 0008 is a change to 0008, because those three are what a build is gated on and a rename detaches the gate from what it was gating.

All three conditions here are untouched and this stays open on them. Every span named in 0008 being emitted by the code that owns it, the suite driving them through a controlled clock, and a test proving the overhead are statements about running code, and there is no language chosen, no build and no test command in this tree to assert them against.

One of the three is worth naming more precisely than that, because the record narrows it rather than leaving it whole. The bound on the overhead with no subscriber is stated as a property and not as a time: no clock read, no allocation and no lock. A duration written into a record today would be a number with no command behind it, and #65 is where a measured one comes from. So this condition stays open on the test, and it is also open on the number, which the record names as owed rather than supplying.