Add scheduled check comparing the SDK metrics reference with the SDK sources

[Duncanma]

Follow-up to #4985 (content fixes) and #4986 (internal consistency check).

#4986 proves docs/references/sdk-metrics.mdx doesn't contradict itself. It can't tell you the page is wrong — a metric that never existed, or an availability list missing an SDK, passes it happily. Those were the errors the manual audit in #4985 actually found. This check closes that gap by comparing the page against the metric definitions in sdk-rust, sdk-go, and sdk-java.

What it reports

• Documented metrics that no SDK defines (a wrong name).
• Availability lists that disagree with the sources, in either direction.
• Metrics an SDK defines that the page omits, unless they're in the baseline.
• Baseline entries the SDKs no longer define.

Validation

Run against the page as merged, it reports zero wrong names and zero availability mismatches across all 48 metrics. That independently reproduces the availability table I verified by hand for #4985, which is the main evidence the extractors are trustworthy.

Design notes

Advisory, not a merge gate. The SDK default branches run ahead of released versions, so drift here is often "the SDK changed," not "the docs are wrong." A weekly job opens (and updates, and later closes) a single tracking issue. Exit codes are 0 clean, 2 drift, 1 the comparison couldn't run.

A constant that's declared but never referenced isn't emitted. sdk-go declares WorkflowActiveThreadCount and never uses it; trusting the declaration would wrongly credit Go with that metric. The check greps each repo for the identifier and drops unreferenced ones. This caught a second case: WorkflowTaskNoCompletionCounter is also dead in sdk-go, so workflow_task_no_completion is Java-only. My review packet on #4985 listed it under Go — that was wrong.

Definition files are listed explicitly, not discovered. If one is renamed upstream the check fails loudly with exit 1 rather than quietly reporting that an SDK stopped emitting metrics.

The baseline is the record of what we chose not to document. bin/metrics-baseline.json holds the 13 metrics the SDKs define but the page omits, so the job only alerts on new drift. Three are confirmed deprecated aliases. The nine with an empty note are the open questions — I didn't want to invent justifications for metrics I haven't confirmed with the SDK team:

Metric	SDKs
activity_task_received	Core
local_activity_error	Go
request_resource_exhausted, long_request_resource_exhausted	Go
resource_slots_cpu_pid_output, resource_slots_mem_pid_output	Core, Java
sticky_cache_thread_forced_eviction	Java
workflow_task_execution_total_latency	Java
workflow_task_heartbeat	Java
workflow_task_no_completion	Java

The two resource_slots_*_pid_output gauges look like tuner internals, and the two *_resource_exhausted counters look like genuine gaps in the page. Both are worth a second opinion before I either document them or write a note.

Test plan

• node --test bin/check-metrics-against-sdks.test.js — 38 tests, offline, over fixture snippets in each language
• Clean run exits 0; a removed baseline entry and a stale one both surface and exit 2
• Deleting a definition file produces the "renamed upstream" error and exit 1
• Fresh clone into an empty cache dir works; three shallow clones total 37MB and take ~6s
• yarn check:metrics still passes and its 22 tests still pass
• Confirm the scheduled run opens the tracking issue as expected (needs a workflow_dispatch after merge)

┆Attachments: EDU-6859 Add scheduled check comparing the SDK metrics reference with the SDK sources

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
temporal-documentation	Ready	Preview	Jul 31, 2026 10:29pm

[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.