feat(api): expose application business metrics via RoadRunner

[vokomarov]

Problem statement

The API emitted only RoadRunner framework metrics. There was no visibility into application-level behaviour — auth outcomes, user growth and engagement, transactional activity, or database load — so dashboards and alerts could not be built on anything the product actually does.

Changes

Adds application business metrics on top of the RoadRunner metrics plugin, served on the existing :2112 endpoint.

New series:

Metric	Type	Labels
app_db_queries_total	counter	–
app_db_query_duration_seconds	histogram	–
app_auth_logins_total	counter	method, result
app_auth_registrations_total	counter	result
app_users	gauge	state (verified/unverified)
app_users_active	gauge	window (daily/weekly/monthly)
app_charges_created_total / app_charges_deleted_total	counter	type
app_wallets_created_total / app_wallets_archived_total	counter	–
app_tags_created_total	counter	–
app_tag_assignments_total	counter	–

Implementation notes:

• Collectors are declared statically in .rr.yaml (metrics.collect:) — the plugin registers them once before workers boot, so there is no per-worker declare() race flooding the logs.
• AppMetrics is a thin typed facade over MetricsInterface (App\Service\Metrics). Every emission is wrapped so a metrics outage cannot break a user request; MetricsCollectConfigTest fails the build on any drift between AppMetrics::definitions() and the YAML.
• NullMetrics is bound when APP_ENV=testing (no RR RPC relay in tests).
• DB query count/latency are fed by a Cycle\Database\LoggerFactoryInterface decorator that reads only the elapsed value — no SQL text is stored.
• app_users / app_users_active are not event-driven, so a schedule:work service block in .rr.yaml runs AppUserMetricsRefresher every 5 minutes to recompute and push them.
• New non-unique index on users.active_at (migration + entity annotation) keeps the active-user COUNT queries index-backed.

Emission points wired into the four Auth controllers, GoogleAuthService, ChargeWalletService, WalletService, and TagService.

Verification

• Independent code review over 4 rounds; final round returned no material findings. Confirmed against the RoadRunner metrics v5.1.4 and Spiral roadrunner-metrics sources that the implementation uses the documented approach (static collect: + MetricsInterface add/set/observe) and not a custom transport.
• composer checks — new suites green: tests/Unit/Service/Metrics (25), tests/Feature/Metrics (18), UserRepositoryTest (3). phpcs (PSR-12) and psalm (strict) clean. The only failures are three pre-existing, unrelated tests (JwksControllerTest ×2, InternalHeadersMiddlewareTest), reconfirmed by reproducing them against a clean checkout.
• Migration applies and rolls back cleanly against the real database.
• Isolated rr serve: zero collector-declare warnings at boot; schedule:run populates app_users / app_users_active end to end; /metrics on :2112 exposes all twelve series.

Note for the deploy

compose.app.yml caps the api container at mem_limit: 768m with 6 HTTP workers budgeted. This change adds a resident schedule:work process plus a transient per-minute schedule:run kernel boot. Worth watching OOM headroom on first deploy, or raising the limit pre-emptively.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.69%. Comparing base (1a294bc) to head (22ff37b).

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #226      +/-   ##
============================================
+ Coverage     99.68%   99.69%   +0.01%     
- Complexity     1431     1480      +49     
============================================
  Files           221      227       +6     
  Lines          4815     4981     +166     
============================================
+ Hits           4800     4966     +166     
  Misses           15       15              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.