Uh oh!
There was an error while loading. Please reload this page.
docs(faq): drop phantom "queue depth" from recommended metrics - #105
Merged
Conversation
The "What metrics should I monitor?" answer recommended `queue depth`, a signal the runtime does not emit. On objectstack@origin/main the only hits for queue_depth / queue_size / jobs_pending / queue_length are four placeholder names inside unit tests of the metrics registry itself; no runtime call site registers such a series, and packages/observability/src/semconv.ts declares no queue gauge. Delete it, with nothing in its place. `job_schedule_failures_total` is deliberately NOT substituted: it counts a DECLARED job that could never be handed to the job service, which answers "this job will never run", not "the queue is backing up" — recommending it as the queue signal would be a second inaccuracy, quieter than the first. No "may not exist" annotation either: a signal an operator is told to monitor, annotated as unavailable, is still one they go looking for. The three survivors were each verified against objectstack@origin/main rather than inherited from the card. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CJPxtTxoxTUnjNdTbiEaRa
os-zhuang
marked this pull request as ready for review
August 18, 2026 14:46
Uh oh!
There was an error while loading. Please reload this page.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes#96
Deletes
queue depthfrom the "What metrics should I monitor?" answer incontent/docs/resources/faq.mdx. Nothing takes its place.Verified at commit
7c10559.The phantom signal
queue depthis emitted by nothing. Onobjectstack@origin/main(890b38f04),one grep carrying both the phantom terms and a known-real control term:
The four queue hits are arbitrary placeholder names inside unit tests of the
metrics registry itself — no runtime call site registers such a series.
semconv.tsdeclares 13 names and none is a queue gauge. The control term(
job_schedule_failures_total) returns from the same command, so the zero-hiton the queue terms is a real zero and not a broken grep.
What is deliberately NOT done
job_schedule_failures_totalcounts a declaredjob that could never be handed to the job service — "this job will never
run", not "the queue is backing up". Recommending it as the queue signal
would be a second inaccuracy, quieter than the first and therefore worse.
annotated as unavailable, is still one they will go looking for.
zero operator pull, and "depth" may not be well-defined across the
adapter-backed job service.
The three survivors were checked, not inherited
This card exists because a list of recommended signals was never checked, so a
shorter unchecked list would repeat the defect at smaller scale. Each remaining
signal, against
objectstack@origin/main:http_requests_total,statuslabelpackages/runtime/src/observability/instrument.ts:106http_request_duration_mshistogrampackages/runtime/src/observability/instrument.ts:112GET /api/v1/readypackages/runtime/src/http-dispatcher.ts:532; probe pathpackages/cli/src/commands/serve.ts:3400Both HTTP series are declared in
semconv.tsand emitted from a handler that isactually wired in —
instrumentRouteHandleris invoked atpackages/runtime/src/dispatcher-plugin.ts:710, not merely exported. Thereadiness route is an exact
GET /readyreturning 200 when running and 503while booting, shutting down, or when a driver is down.
Verification
turbo run type-check --filter=@objectos/docs --force— pass,cache bypass, force executing e6d8d09cccc37fbeturbo run build --filter=@objectos/docs --force— pass,cache bypass, force executing fb9f62bc2cf33741enHTML read from.next/server/app/en/docs/resources/faq.html: the answer renders as "5xx rate, p95 latency, readiness (/api/v1/ready)." andqueue depthappears nowhere on the page.check-translations.mjs— exit 0, gate passedcheck-translations.mjs --worklist— exit 0check-translation-ownership.mjs --files— exit 0, "touches 0 translation artifact(s) and 1 other file(s)"English only; the six
faq.*.mdxlocale siblings are untouched. They werealready stale at
origin/mainbefore this change (verified in a throwawaycomparison worktree at
origin/main— the same six are listed stale there), sothis PR does not newly stale them; the next translation pass re-derives them.
operate/observability.mdxis not in this surface and was checked anyway: itrecommends only
http_requests_totaland explicitly explains what the registrydoes not cover. Nothing phantom there.
Generated by Claude Code