refactor(metrics): adopt official client and explicit instrumentation #112

Merged

eleith merged 1 commits from deps/prometheus-client into main 2026-11-01 02:45:43 +00:00

Conversation 0 Commits 1 Files Changed 88

+2080 -909

eleith-gitea-agent Bot commented 2026-10-31 22:40:58 +00:00

Copy link

Copy source

Summary

Closes #100.

• Replace deprecated prom-client with the official @prometheus-io/client 0.16.1 in web and worker; include patch changesets for both apps.
• Keep the existing private, authenticated web-to-worker HTTP bridge and one public scrape endpoint. Worker supports native JSON snapshots while retaining default text output. Preserve enable/token gates and the two-second bound, including response-body reading.
• Aggregate snapshots through native Registry.aggregate(), preserving application/service labels, HELP/TYPE and histogram buckets/sum/count. Validate finite samples rather than silently converting invalid values to zero.
• Make partial collection explicit: worker failure returns web-only HTTP200 with request-local when_worker_scrape_success=0 and a bounded failure code in the same response. No stale worker snapshot; web export failures still fail the scrape.

Instrumentation layout

• Keep Prometheus definitions and recording inside each app's dedicated metrics/ area. Small appointment and worker service facades wire operation observers; plain domain implementations remain metric-free. HTTP booking/ICS handlers explicitly call typed outcome recorders at their decision points—no whole-handler decorators or response-code inference. Auth uses its native hooks.
• Add native ESLint import restrictions to preserve this separation. Worker leaf/batch splits keep the observed service paths explicit without cycles.
• Preserve database writes, transactions, enqueueing, workflow steps/graphs/retries/schedules, authentication and private HTTP behavior. No shared-package, custom server, event-bus or generic instrumentation-framework changes.

Signals and limits

• Add when_appointment_operations_total{action,actor,status}: success/rejected/error operation outcomes, not committed-row counts. An enqueue error after a saved write is an operation error. Expiry counts one invocation even with zero affected rows; bulk actions count each operation.
• Preserve application counters and job handler timing/activity; expose oldest active handler age. Returned/escaped do not mean durable completed/failed, and parked workflows are not active handlers.
• Classify structured SMTP failures and calendar provider-call failures using bounded codes. Physical calendar write/delete coverage includes reconciliation, video booking, cleanup and purge. Details stay in logs/admin history, not labels; SMTP acceptance is not inbox delivery.
• Booking failures now use error rather than database_error. Booking counters cover explicit handled validation/availability/creation outcomes, not every HTTP failure.
• Remove all Node collectors and their background sampling. No scrape-time SQL, durable backlog polling, new metrics service or public worker port. See docs/metrics.md for the operator contract.

Validation

• Independent code, readability and test-value reviews completed; findings applied. Fresh code/readability/test reviews of the final explicit-HTTP-recording refinement are clean.
• Full coverage suites: 1,084 web tests /79files +585 worker tests /52files =1,669 tests /131files, thresholds unchanged. Worker source remained unchanged during the final web-only refinement.
• Web svelte-check: 0 errors, 0 warnings. Worker TypeScript, both app lint scripts and both production builds passed; worker assets built separately.
• Changed/new source formatting, whitespace, import-boundary negative probes and local documentation links passed. Current app-only native JSON/compiled-worker smoke verifies5web/10worker When-only families, shared metadata/labels/status/counts, histograms and invalid-null rejection.
• Strengthened existing actual-route and native workflow tests rather than adding another harness or broad matrix. No E2E/browser, Docker or live-provider run for server-only telemetry.

Local checks used the owner-installed dependency graph. This commit excludes the owner's mise.toml edit and three unrelated sourcemap-codec lock edges; frozen CI must validate the exact committed graph. No CI-policy change, release, version bump, deployment or merge action. Owner will land the PR.

## Summary Closes #100. - Replace deprecated prom-client with the official @prometheus-io/client **0.16.1** in web and worker; include patch changesets for both apps. - Keep the existing private, authenticated web-to-worker HTTP bridge and one public scrape endpoint. Worker supports native JSON snapshots while retaining default text output. Preserve enable/token gates and the two-second bound, including response-body reading. - Aggregate snapshots through native Registry.aggregate(), preserving application/service labels, HELP/TYPE and histogram buckets/sum/count. Validate finite samples rather than silently converting invalid values to zero. - Make partial collection explicit: worker failure returns web-only HTTP200 with request-local when_worker_scrape_success=0 and a bounded failure code in the same response. No stale worker snapshot; web export failures still fail the scrape. ## Instrumentation layout - Keep Prometheus definitions and recording inside each app's dedicated metrics/ area. Small appointment and worker service facades wire operation observers; plain domain implementations remain metric-free. HTTP booking/ICS handlers explicitly call typed outcome recorders at their decision points—no whole-handler decorators or response-code inference. Auth uses its native hooks. - Add native ESLint import restrictions to preserve this separation. Worker leaf/batch splits keep the observed service paths explicit without cycles. - Preserve database writes, transactions, enqueueing, workflow steps/graphs/retries/schedules, authentication and private HTTP behavior. No shared-package, custom server, event-bus or generic instrumentation-framework changes. ## Signals and limits - Add when_appointment_operations_total{action,actor,status}: success/rejected/error operation outcomes, **not committed-row counts**. An enqueue error after a saved write is an operation error. Expiry counts one invocation even with zero affected rows; bulk actions count each operation. - Preserve application counters and job handler timing/activity; expose oldest active handler age. Returned/escaped do not mean durable completed/failed, and parked workflows are not active handlers. - Classify structured SMTP failures and calendar provider-call failures using bounded codes. Physical calendar write/delete coverage includes reconciliation, video booking, cleanup and purge. Details stay in logs/admin history, not labels; SMTP acceptance is not inbox delivery. - Booking failures now use **error rather than database_error**. Booking counters cover explicit handled validation/availability/creation outcomes, not every HTTP failure. - Remove all Node collectors and their background sampling. No scrape-time SQL, durable backlog polling, new metrics service or public worker port. See docs/metrics.md for the operator contract. ## Validation - Independent code, readability and test-value reviews completed; findings applied. Fresh code/readability/test reviews of the final explicit-HTTP-recording refinement are clean. - Full coverage suites: **1,084 web tests /79files +585 worker tests /52files =1,669 tests /131files**, thresholds unchanged. Worker source remained unchanged during the final web-only refinement. - Web svelte-check: **0 errors, 0 warnings**. Worker TypeScript, both app lint scripts and both production builds passed; worker assets built separately. - Changed/new source formatting, whitespace, import-boundary negative probes and local documentation links passed. Current app-only native JSON/compiled-worker smoke verifies5web/10worker When-only families, shared metadata/labels/status/counts, histograms and invalid-null rejection. - Strengthened existing actual-route and native workflow tests rather than adding another harness or broad matrix. No E2E/browser, Docker or live-provider run for server-only telemetry. Local checks used the owner-installed dependency graph. This commit excludes the owner's mise.toml edit and three unrelated sourcemap-codec lock edges; frozen CI must validate the exact committed graph. No CI-policy change, release, version bump, deployment or merge action. Owner will land the PR.

eleith-gitea-agent Bot added 1 commit 2026-10-31 22:40:58 +00:00

refactor(metrics): adopt official client and explicit instrumentation ... c5feeb83a4

Replace prom-client with @prometheus-io/client 0.16.1 and retain the private authenticated web-to-worker bridge with native JSON aggregation and explicit collection health.

Keep Prometheus recording in dedicated metrics modules, use explicit HTTP outcome recorders and operation observers, and document appointment outcomes, bounded provider failures and handler activity. Remove Node collectors and background sampling.

Closes #100

eleith merged commit c5feeb83a4 into main 2026-11-01 02:45:43 +00:00

eleith deleted branch deps/prometheus-client 2026-11-01 02:45:43 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

blocked

Waiting on a prerequisite before work can proceed

bug

Something is not working

enhancement

New feature

No labels

Milestone

No items

No Milestone

Assignees

Clear assignees

eleith-gitea-agent Bot eleith (eleith)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: eleith/when#112