Bound client metric routes and verify the shared SDK metrics contract #205

Delivered in Python SDK 2.10.0

Client metrics use bounded route templates and honor explicitly supplied recorders, with normal Prometheus export.

PyPI 2.10.0 is published at exact qualified source 4f853f396dba5a530ef0815509b16bfddaa9ebc3. Normal registry acceptance passes 334 controls, all 37 source files and all 50 hashed RECORD entries. Docs #212 merged at e530e33ec1303530779f91a0d249666c9f9aca16; its actual Pages deployment and all five affected routes were verified at 16:09 UTC. Current guidance states the minimum version.

Earlier failed observations remain failed. Separate #175/#215 source is outside this release.

Original report and earlier qualification

Current package delivery gate — October 23

The complete 2.10.0 candidate is 4f853f396dba5a530ef0815509b16bfddaa9ebc3, merged as 38b5a639262bebcf3fd0e67c6ec42ab16bc3a966 with the same tree. Fresh exact artifact hashes and installation proof: all 17 applicable normal gates, both distributions' smoke/metadata checks, 37 installed source/RECORD matches, 272 controls and actual console acceptance/refusal pass. The earlier 12b5f372 proof remains its own retained earlier cohort; the complete new candidate supersedes it only after all fresh proof passed.

Untagged and unpublished: existing #197 Trusted Publisher account setup remains required. No token fallback or repeated human account request. Actual registry installation and consumer acceptance remain open; draft #212 prepares versioned guidance and stays draft until those real delivery gates pass. Security-only 2.9.1/2da02a7a remains separate. No protocol-floor, major or automatic runtime/Cloud adoption follows.

Problem

Python client request metrics retain task and session identifiers in route tags for newer worker operations. Each distinct ID creates a new time series and exposes the identifier to the metrics backend. Unknown paths also retain literal segments.

Reproduced with the actual Client and InMemoryMetrics on main 2da02a7ac8a68a7cd4267e86ef10e0198a309592 (also unchanged in #204's candidate). HTTP transport was isolated with httpx.MockTransport; no live runtime or customer identifiers were used. Calling the public approve_update_validation_task() and renew_worker_session() methods for two synthetic IDs emits four separate route values:

• /worker/update-validation-tasks/task-synthetic-a/approve
• /worker/update-validation-tasks/task-synthetic-b/approve
• /worker/sessions/session-synthetic-a/heartbeat
• /worker/sessions/session-synthetic-b/heartbeat

The shared metrics contract in durable-workflow/.github#233 / PR #245 requires bounded route templates without IDs or raw URLs, and a bounded unknown route for unrecognized operations. Its existing reference records Python's metric names and tag keys, not conformance of these values.

This is distinct from #167's exception-class diagnostics, request-cancellation outcome and transport retry decision. Do not treat a helper-only route test as proof of actual recorder emissions.

Acceptance

• Normalize variable segments for supported SDK client routes, including update-validation tasks and worker sessions. Preserve the meaning of known static operations and documented placeholders; distinguish poll and task operations.
• Unknown operations use one bounded unknown route. Query strings, variable IDs, payloads, credentials and raw URLs do not appear in core metric labels.
• Exercise the actual Client recorder through representative public APIs with differing synthetic workflow/run/task/worker/session identifiers, success/failure/transport paths, and synthetic secret query values. Identifiers and query changes must not create additional route series.
• Pin the shared metrics contract and compare actual recorder names, instrument operations, exact tag keys, string values, count increments of one and nonnegative monotonic seconds. Cover worker observations, default no-op, client-to-worker inheritance and explicit override.
• Keep compatible names, instrument types, units and tag keys; document corrected route values and limits. A contract list alone does not complete SDK adoption.
• Complete source qualification, compatible publication and normally installed adapter acceptance. The existing Raise the certifi trust floor (2.9.1) #197 registry-side Trusted Publisher dependency remains; no upload-token fallback or release-tag bypass.

Current delivery state

Source delivered through PR #206, merged at 4c79bc49fd94924fcdb52a1a9548226f2d2cabe2 on October 23 at 10:24:05 UTC. Tree f7ea0e4f1a8e76030f71875a9eafe95e0ce7267f exactly matches candidate 2b3893ab. All 18 normal checks pass, including supported Python versions, actual integration and target qualification. Final Sonar has zero OPEN/CONFIRMED findings. The completed remote branch is deleted and independently absent.

The static route table bounds variable task, session, workflow, stream and Nexus names; unknown paths use unknown. The shared metrics fixture/provenance exactly matches .github commit 73e8fc323e4f46322945a007e54a546395904f79, SHA256 c456f4f434c601fa26f0caba07ef0fd29f548ca8f5fc29ba2f6430f01e32c0f0. Explicit and inherited valid falsey recorders retain None-only selection. The peer contract review is acknowledged.

Functional 9e579edf full local qualification passes 3,201 tests / two skips / 105 integration deselections, 136.32 seconds. Its focused 69 metric controls pass; final target 2b3893ab passes 184 combined metrics/TLS/harness/backoff controls in 8.15 seconds. The six actual falsey-recorder counterfactual failures remain recorded. Earlier full/isolated process-readiness failures remain failures, with no established physical cause or guard relaxation; later passes do not rescue those originals.

Remaining: compatible publication and normally installed adapter acceptance after #197 Trusted Publisher setup. Source guidance explicitly marks the behavior unreleased. Fresh-main CI 39938834755 is independent and pending. Shared .github #233 remains open for published/installed cross-language delivery. No tag/version change is included.