Problem
The developer portal now has a live latency/uptime view, but its latency data is only partial. Today it comes from:
- the portal synthetic probe, fired every 5 minutes
- portal-originated Run traffic
That does not measure all real partner production /calculate traffic. The household API already records value-free calculate analytics with trusted client_id, status code, requested/resolved channel, model version, endpoint, method, and variable usage, but it does not store request duration.
Goal
Record first-party calculate request latency in policyengine-household-api so the portal can show true live latency and uptime for production partner API traffic.
Proposed work
- Add a
duration_ms or equivalent integer column to calculate_requests via Alembic migration.
- Measure wall-clock request duration around the calculate handler in the analytics decorator.
- Persist duration for successful responses, error responses, and exceptions where analytics is enabled.
- Expose latency/uptime aggregations from the analytics API, either by extending
/analytics/calculate/requests or adding a focused endpoint.
- Support filters needed by the portal:
- time window / start and end time
- resolved channel:
current / frontier
- optionally client_id for staff-only partner drilldown, once authorization rules are decided
- Return enough aggregate data for the portal to show p50, p95, p99, count, error count, and uptime by time bucket.
Acceptance criteria
- Real authenticated
/calculate requests produce analytics rows with trusted client_id and duration_ms.
- Failed calculate requests and thrown exceptions record status/error state and duration where possible.
- Analytics endpoint can return bucketed latency and uptime for current/frontier over recent windows.
- No request bodies, response bodies, household values, entity IDs, or other sensitive values are logged.
- Unit tests cover migration/model changes, duration recording, exception paths, and analytics aggregation.
- Deployed analytics metadata test is updated or extended to assert duration is recorded.
Context
Portal PR: https://github.com/PolicyEngine/policyengine-developer-portal/pull/20
Current limitation in the portal: the dashboard is useful as an availability canary, but it is not yet true production partner latency because household API does not emit first-party latency metrics.
Problem
The developer portal now has a live latency/uptime view, but its latency data is only partial. Today it comes from:
That does not measure all real partner production
/calculatetraffic. The household API already records value-free calculate analytics with trustedclient_id, status code, requested/resolved channel, model version, endpoint, method, and variable usage, but it does not store request duration.Goal
Record first-party calculate request latency in
policyengine-household-apiso the portal can show true live latency and uptime for production partner API traffic.Proposed work
duration_msor equivalent integer column tocalculate_requestsvia Alembic migration./analytics/calculate/requestsor adding a focused endpoint.current/frontierAcceptance criteria
/calculaterequests produce analytics rows with trustedclient_idandduration_ms.Context
Portal PR: https://github.com/PolicyEngine/policyengine-developer-portal/pull/20
Current limitation in the portal: the dashboard is useful as an availability canary, but it is not yet true production partner latency because household API does not emit first-party latency metrics.