Add a consistency check for the SDK metrics reference

[Duncanma]

Summary

Adds a CI check that validates the internal consistency of docs/references/sdk-metrics.mdx, so the class of drift fixed in #4985 cannot silently return.

The page states the same facts twice — once in the summary table, once in the per-metric section — and nothing kept them in sync. That is how the table came to link two metrics to each other's anchors and to disagree with five sections about which SDKs emit a metric.

Stacked on #4985. Based on fix/sdk-metrics-reference-accuracy rather than main, because the check asserts the reference page is clean and main still has the 14 problems that #4985 fixes. GitHub will retarget this to main when the parent merges.

What it checks

• Every table anchor matches its metric name
• Table rows and sections map one-to-one
• Table and section agree on metric type and availability
• Headings are backticked metric names, keeping anchors predictable
• SDK names, metric types, "Emitted by" values, and tag names come from a known vocabulary
• No metric description claims a unit, which would contradict the units admonition

The tag vocabulary is a single constant checked against both the shared key list at the top of the page and each metric's own Tags line, so a hyphen/underscore slip in either place fails rather than merely looking inconsistent.

Does it work?

Replayed against the pre-fix page from main, it reports 14 problems — every bug found by hand during the #4985 audit except the two that were wrong consistently in both the table and the section:

shared tag list: unknown tag `task-queue`
activity_task_error: availability disagrees (table "Go", section "Go,")
nexus_poll_no_task: availability disagrees (table "Core, Go, Java", section "Go, Java")
nexus_task_execution_failed: availability disagrees (table "Core, Go, Java", section "Go, Java")
nexus_task_execution_latency: availability disagrees (table "Core, Go, Java", section "Go, Java")
nexus_task_endtoend_latency: availability disagrees (table "Core, Go, Java", section "Go, Java")
num_pollers: availability disagrees (table "Core, Go", section "Core, Go, Java")
resource_slots_mem_usage: table links to #resource_slots_cpu_usage
resource_slots_cpu_usage: table links to #resource_slots_mem_usage
unregistered_activity_invocation: availability disagrees (table "Go", section "Go,")
activity_schedule_to_start_latency: description says "in seconds", which contradicts the units admonition
activity_task_error: unknown SDK "" in section availability
nexus_task_schedule_to_start_latency: description says "in seconds", which contradicts the units admonition
unregistered_activity_invocation: unknown SDK "" in section availability

Scope and limits

It reads no SDK source. It cannot tell you a documented metric name is wrong — it would not have caught local_activity_succeeded_endtoend_latency, nor sticky_cache_total_forced_eviction missing Core, because those were wrong consistently in both places. Catching those needs a scheduled diff against the SDK repos, which is a separate, more fragile piece of work worth doing next. The header comment states this so a green check is not mistaken for "verified against the SDKs."

No alphabetical-ordering rule. The table is mostly sorted, but the five Nexus rows are not, so the rule would fail today and force a reorder outside this PR's scope.

Implementation notes

Follows the existing bin/check-redirects-for-moved-pages.js pattern: exported functions, a main() that prints problems and exits non-zero, plus a colocated .test.js. Runnable locally as yarn check:metrics.

The workflow needs no yarn install since everything is plain Node, and it runs the checker's own unit tests before the checker itself.

Test plan

• yarn check:metrics passes on the current page (48 metrics consistent)
• 22 new tests pass, one per rule, each seeded with a bug that actually shipped
• Full suite green, 39 to 61 tests
• Replay against the pre-fix page reports the 14 problems above

┆Attachments: EDU-6840 Add a consistency check for the SDK metrics reference

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
temporal-documentation	Ready	Preview	Jul 30, 2026 11:01pm

[github-actions]

📖 Docs PR preview links

This PR does not change any pages in /docs. If you make updates, links to the modified pages will appear here.