`objectstack serve` registers no `ObservabilityServicePlugin`, so `observability:metrics` is unregistered — every consumer but the dispatcher resolves to nothing

[huangyiirene]

Found while implementing the transport-owned http_requests_total seam for #9650 (PR #9746). Filed unassigned; not graded by the filing seat.

The claim, measured on 8957c72227 (branch head, origin/main merged at 9ff11921a2)

OBSERVABILITY_METRICS_SERVICE ('observability:metrics') has exactly one registrar in the whole repo — ObservabilityServicePlugin.init(), packages/runtime/src/observability/observability-service-plugin.ts:85.

A repo-wide sweep finds no host that registers it:

grep -rn "ObservabilityServicePlugin" --include=*.ts packages/ apps/ examples/

returns only the plugin's own definition, its own test, and three JSDoc mentions pointing readers at it. packages/cli/src/commands/serve.ts never names it.

What serve.ts does instead (:2564): builds one registry from env and threads it into a single consumer.

const observability = await buildServeObservability();
await kernel.use(createDispatcherPlugin({ ..., observability, ... }));

The transport is constructed 800 lines earlier and gets nothing (serve.ts:1758):

const serverPlugin = new HonoServerPlugin({ port });

Consequences, all measured or read on the current ref

• The dispatcher is the only plugin in a shipped CLI deployment whose metrics reach a backend. Every other consumer follows the canonical chain documented on ObservabilityServicePlugin — explicit option, then observability:metrics, then no-op — and lands on the no-op:
  • packages/services/service-cache/src/cache-service-plugin.ts:109
  • packages/services/service-storage/src/storage-service-plugin.ts (same shape)
  • the SEMCONV families those emit (cache_lookups_total, storage_operations_total, …) are therefore dark in every objectstack serve deployment, however OS_OBS_EXPORTER is set.
• It also blocks http_requests_total never sees auth routes or the REST data API — the two highest-traffic inbound surfaces are outside the only HTTP counter the docs tell operators to monitor #9650 from being discharged end-to-end. The transport seam landing in PR fix(hono-server): emit http_requests_total from the transport so every inbound mount is counted (#9650) #9746 follows the same chain, so with neither the option nor the service present it installs no middleware and http_requests_total keeps reporting dispatcher routes only. The fix is correct at the seam and inert at the host.

Why this is not a one-line change, i.e. why it is filed rather than folded in

buildServeObservability() is called once, deep in the dispatcher block. Calling it a second time at the transport's construction site would build a second exporter — for OS_OBS_EXPORTER=otlp that means two OtlpHttpMetricsRegistry instances with two independent flush timers. So the repair is a choice, not a rewrite:

1. hoist/memoize buildServeObservability() and pass the same block to new HonoServerPlugin({ port, observability }) — narrow, leaves cache/storage still dark;
2. register ObservabilityServicePlugin with that block before every consumer and let the documented chain do the rest — one registration, lights up transport, cache and storage together, and matches what the plugin's own JSDoc tells hosts to do ("Register this plugin before any plugin that wants to consume the services").

Option 2 looks right and is the reason this is a card rather than a rider: it changes plugin ordering in serve.ts and turns three currently-silent metric families on at once, which deserves a deliberate decision rather than a side effect of an unrelated PR.

Scope note

packages/cli/src/commands/serve.ts was read only — no edit was made from #9650's dispatch, whose file surface did not include it.

---

Generated by Claude Code

[os-warren]

Triage: lands in domain:cli (packages/cli/src/commands/serve.ts). Bug, not Feature — this is a declared-registration gap (the plugin exists, its consumer chain is documented, serve.ts just never wires it), not a new capability. pm:queue.

Rationale: filer's Option 2 (register ObservabilityServicePlugin before its consumers, per the plugin's own JSDoc) is the mechanical-boundary-test pass — it restores declared=enforced for an existing documented chain rather than expanding any accepted surface. The "turns on 3 metric families at once" concern is real but is a blast-radius note for the dispatching seat, not a product decision: no new key is declared, no consumer's contract changes shape. Also blocks #9650's end-to-end discharge (transport seam is inert without this) — dispatch should consider sequencing/priority accordingly. Blocked-by relationship noted on sibling cards #9833/#9834.

---

Generated by Claude Code

---

Generated by Claude Code

[huangyiirene]

Claim: PM loop round 25
Session: session_01WeN7F6jQFpcqW2BN56RdPa
Branch: claude/issue-9832-serve-registers-observability
Worktree: objectstack-issue-9832
Domain: domain:cli
File surface: packages/cli/src/commands/serve.ts (the plugin-registration region — buildServeObservability()'s call site and the HonoServerPlugin construction at :1758), plus a pin and .changeset/** (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — node scripts/pm/dispatch-gates.mjs --tier returns no path-derived mandate, ⛔ not recalled. Held at default rather than lowered: serve.ts is the hottest file in the repo and the change is a plugin-ordering edit, which is judgment, not wiring
Clause-②: no — registering an already-declared service. Nothing about what any route accepts or rejects changes, and no public surface widens; the metric families involved are already declared in SEMCONV
Serial constraints cleared: packages/cli/src/commands/serve.ts 🔓 free — #9821 landed (9ff11921a) and nothing else in flight names it. ⚠️ Sibling #9813 holds packages/runtime/src/dispatcher-plugin.ts — see the boundary below. #9585 (action-execution.ts / domains/actions.ts) is disjoint

Why this one is first in the round

This card blocks #9650's end-to-end discharge: that card's ruled transport seam landed (152bff8fcd) and is inert at the host because neither link of the resolution chain exists in a shipped objectstack serve. #9650 sits pm:blocked on this card, so this is the unblocking work, not a follow-up.

Scope — triage endorsed Option 2, and named the blast radius as yours to weigh

Option 2: register ObservabilityServicePlugin with the buildServeObservability() block before every consumer, and let the documented chain (explicit option → observability:metrics service → nothing) do the rest. That matches the plugin's own JSDoc — "Register this plugin before any plugin that wants to consume the services."

⛔ Option 1 (hoist/memoize and hand the block only to the transport) is the narrower fix and is not what triage endorsed — it leaves cache and storage still dark. Take it only if measurement rules out Option 2, and say why.

⚠️ The blast radius is real and is the thing to be careful about, not to avoid: this turns on three currently-silent metric families at once (http_requests_total at the transport, cache_lookups_total, storage_operations_total). Triage's judgement — which I share — is that this is a blast-radius note for the dispatching seat, not a product decision: no new key is declared and no consumer's contract changes shape. Measure what actually starts emitting and report it.

⚠️ The trap the card names explicitly: buildServeObservability() is called once, deep in the dispatcher block. Calling it a second time builds a second exporter — with OS_OBS_EXPORTER=otlp that is two OtlpHttpMetricsRegistry instances with two independent flush timers. ⇒ Whatever shape you choose, prove there is exactly one registry instance, and pin it.

PM mechanism assumptions — measure; falsifying them is a good run

• That registering the plugin before its consumers is sufficient — i.e. that HonoServerPlugin, cache and storage all actually resolve the service once it exists. ⭐ Verify by booting, not by reading the chain: http_requests_total never sees auth routes or the REST data API — the two highest-traffic inbound surfaces are outside the only HTTP counter the docs tell operators to monitor #9650's whole lesson was a seam that was correct in code and inert in the deployment. A test that asserts registration without asserting emission would repeat exactly that.
• That plugin ordering can be changed safely at that point in serve.ts. If moving the registration earlier breaks a boot-ordering assumption, that is a report, not something to work around.
• That no packages/spec change is needed. If one is, STOP and report — that package is the domain:spec seat's.

⛔ Boundary

packages/runtime/src/dispatcher-plugin.ts is held by sibling card #9813 this round. It is out of your surface. If the fix needs it — for instance to stop the dispatcher's own instrumentRouteHandler double-counting once both emitters share a registry — STOP and report: that is #9833's scope, already filed, and sequencing it is my call.

Gates

Re-derive with node scripts/pm/dispatch-gates.mjs from the actually changed paths. ⚠️ Known gap, three confirmed instances (#9721 / #9700): it names neither pnpm lint nor check:slot-lookup — run pnpm lint regardless. Read verdicts from reported counts, ⛔ never a piped exit code.

Report at draft-PR time — ⛔ do not wait on CI. ⚠️ Post the report as an issue comment on this card with the os-dev-report marker first, and read it back — the terminal copy is the accelerator, ⛔ not the record; that channel silently dropped two reports this shift.

---

Generated by Claude Code