Skip to content

docs(faq): drop phantom "queue depth" from recommended metrics - #105

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-96-queue-depth-phantom-signal
Aug 18, 2026
Merged

docs(faq): drop phantom "queue depth" from recommended metrics#105
os-zhuang merged 1 commit into
mainfrom
claude/issue-96-queue-depth-phantom-signal

Conversation

@os-zhuang

Copy link
Copy Markdown
Contributor

Fixes#96

Deletes queue depth from the "What metrics should I monitor?" answer in
content/docs/resources/faq.mdx. Nothing takes its place.

Verified at commit 7c10559.

The phantom signal

queue depth is emitted by nothing. On objectstack@origin/main (890b38f04),
one grep carrying both the phantom terms and a known-real control term:

git grep -nE 'queue_depth|queueDepth|queue_size|queueSize|jobs_pending|queue_length|queueLength|job_schedule_failures_total' origin/main -- '*.ts' '*.tsx'
packages/observability/src/__tests__/otlp-http.test.ts:90: reg.gauge('queue_size', 7);
packages/observability/src/__tests__/otlp-http.test.ts:102: const gauge = metrics.find((m: any) => m.name === 'queue_size');
packages/observability/src/semconv.ts:56: jobScheduleFailuresTotal: 'job_schedule_failures_total',
packages/runtime/src/observability/metrics.test.ts:58: m.gauge('queue_depth', 3);
packages/runtime/src/observability/metrics.test.ts:59: m.gauge('queue_depth', 7);

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.ts declares 13 names and none is a queue gauge. The control term
(job_schedule_failures_total) returns from the same command, so the zero-hit
on the queue terms is a real zero and not a broken grep.

What is deliberately NOT done

  • No substitute metric.job_schedule_failures_total counts a declared
    job 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.
  • No "may not exist" annotation. A signal an operator is told to monitor,
    annotated as unavailable, is still one they will go looking for.
  • No framework card for a queue-depth gauge. Deferred on triage's ruling:
    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:

SignalBacking seriesLive emitter
5xx ratehttp_requests_total, status labelpackages/runtime/src/observability/instrument.ts:106
p95 latencyhttp_request_duration_ms histogrampackages/runtime/src/observability/instrument.ts:112
readinessGET /api/v1/readyroute registered packages/runtime/src/http-dispatcher.ts:532; probe path packages/cli/src/commands/serve.ts:3400

Both HTTP series are declared in semconv.ts and emitted from a handler that is
actually wired in — instrumentRouteHandler is invoked at
packages/runtime/src/dispatcher-plugin.ts:710, not merely exported. The
readiness route is an exact GET /ready returning 200 when running and 503
while booting, shutting down, or when a driver is down.

Verification

  • turbo run type-check --filter=@objectos/docs --force — pass, cache bypass, force executing e6d8d09cccc37fbe
  • turbo run build --filter=@objectos/docs --force — pass, cache bypass, force executing fb9f62bc2cf33741
  • Rendered en HTML read from .next/server/app/en/docs/resources/faq.html: the answer renders as "5xx rate, p95 latency, readiness (/api/v1/ready)." and queue depth appears nowhere on the page.
  • check-translations.mjs — exit 0, gate passed
  • check-translations.mjs --worklist — exit 0
  • check-translation-ownership.mjs --files — exit 0, "touches 0 translation artifact(s) and 1 other file(s)"

English only; the six faq.*.mdx locale siblings are untouched. They were
already stale at origin/main before this change (verified in a throwaway
comparison worktree at origin/main — the same six are listed stale there), so
this PR does not newly stale them; the next translation pass re-derives them.

operate/observability.mdx is not in this surface and was checked anyway: it
recommends only http_requests_total and explicitly explains what the registry
does not cover. Nothing phantom there.


Generated by Claude Code

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
os-zhuang marked this pull request as ready for review August 18, 2026 14:46
@os-zhuang
os-zhuang merged commit d04de81 into mainAug 18, 2026
2 checks passed
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

faq.mdx still recommends monitoring "queue depth", a second signal the runtime does not emit

2 participants

@os-zhuang@claude