ADORSYS-GIS / ADORSYS-GIS/converse-frontends
[Ticket]: Usage API — expose latency/percentile fields
- Ngôn ngữ chính
- TypeScript
- Star
- 0
- Fork
- 0
- Merge trung bình
- 1 giờ 49 phút
- Pull request đã merge (30 ngày)
- 253
Mô tả
## Type
Feature
## Summary
We need the usage API (`openapi/usage.backend.yaml`, owned by the backend team) to expose
latency/percentile fields on its usage series response because the console's LATENCY DISTRIBUTION
dashboard (ADR 0008) has no data source without them. Expected result: `UsageSeriesPoint` (or an
equivalent response shape) carries a latency or percentile field the console can chart.
**The console cannot resolve this.** `openapi/usage.backend.yaml` is generated from the backend's
own contract; the console can only consume what it documents. This ticket exists so Epic 4's
latency-dashboard ticket has something concrete to point at instead of silently staying blocked.
## Intent
ADR 0008 specifies a per-model latency distribution dashboard (histogram/ridgeline) as part of the
console's usage dashboards. The intent of this ticket is to get the backend to add the field(s)
that make that dashboard buildable at all — today it is not a client-side gap, it is a contract
gap: the data literally does not exist in the documented response shape.
## Source of truth (links)
- https://github.com/ADORSYS-GIS/converse-frontends/blob/main/docs/adr/0008-console-shell-inversion-and-visual-direction.md
- https://github.com/ADORSYS-GIS/converse-frontends/blob/main/openapi/usage.backend.yaml
## Current Behavior
`UsageQueryResponse.UsageSeriesPoint` in `openapi/usage.backend.yaml` carries `requests`,
`usage_value`, `total_cost`, and `tokens` — and no latency or percentile field of any kind. ADR
0008 (lines 200 and 297) calls for "per-model latency distribution (histogram/ridgeline)" as a
dashboard section. The console's Overview screen has a LATENCY DISTRIBUTION — p95 BY MODEL section
that, per Epic 4's own ticket for it, cannot be wired from the documented contract as it stands
today.
## Expected Behavior
The usage API response shape includes a latency or percentile field (e.g. p50/p95/p99 per
model, or raw latency samples the console can aggregate) that the console can query and chart
without inventing or approximating a value client-side.
## Acceptance Criteria
- [ ] Given the usage API contract, when the console queries `UsageSeriesPoint` (or equivalent),
then a latency/percentile field is present and documented in `openapi/usage.backend.yaml`.
- [ ] Given the new field exists, when the console's LATENCY DISTRIBUTION dashboard ticket
(Epic 4) is picked up, then it has a real field to bind to instead of a blocked/removed state.
- [ ] Error cases are handled safely: N/A to this ticket directly — the console-side error handling
for the new field is scoped to Epic 4's own ticket once this lands.
- [ ] Existing behavior is not broken: no existing `UsageSeriesPoint` fields are removed or
reshaped by this addition.
- [ ] Relevant tests are added or updated: backend-side, out of scope for this ticket's console
authorship; console-side test coverage lands with Epic 4's ticket once the field exists.
- [ ] Verification evidence is provided (see below).
## Out of Scope
- Building the console's LATENCY DISTRIBUTION dashboard itself — that is Epic 4's ticket, which is
explicitly blocked on this one.
- Deciding the exact shape (raw samples vs. pre-aggregated percentiles) — that is the backend
team's design call; this ticket only states the console's need, not the implementation.
- Any other usage-API field gap not related to latency.
## Technical Context
- `openapi/usage.backend.yaml` — the generated contract `packages/api-rest` is built from.
- ADR 0008 lines 200 and 297 name "per-model latency distribution (histogram/ridgeline)"
explicitly as a planned dashboard.
- Epic 4's "LATENCY dashboard — decide and act" ticket is the console-side consumer that is
blocked on this; once this field exists, that ticket's AC becomes "wire it," not "decide whether
to remove the section."
## Risks
| Risk | Mitigation |
| --- | --- |
| Backend never prioritizes this, and the LATENCY DISTRIBUTION section stays permanently removed/blocked | Epic 4's ticket already has a fallback AC: render an honest blocked state instead of fabricating data |
| Field shape chosen by the backend doesn't match what a histogram/ridgeline needs (e.g. only p95, no distribution) | Flag on this ticket once the shape is proposed, before Epic 4's ticket starts building against it |
## Test Plan
Not applicable to this ticket directly — verification is that the field appears in
`openapi/usage.backend.yaml` and the regenerated `packages/api-rest` client exposes it in its
generated types.
## Verification evidence
Pending backend team response. To close this ticket: link the backend PR/release that adds the
latency/percentile field, and confirm the field name(s) as they will appear in the regenerated
`packages/api-rest` types.
## Human accountable owner
@stephane-segning
## AI Usage Declaration
Ticket decomposition
## Human verification completed
- [ ] I understood the intent
- [ ] I checked the source of truth
- [ ] I reviewed all AI-generated text/code
- [ ] I verified the implementation manually
- [ ] I verified the tests
- [ ] I checked for hallucinated assumptions
- [ ] I documented remaining risks
- [ ] I am the accountable owner and accept responsibility for this ticket.
Hướng dẫn đóng góp
Đánh giá
Issue này chưa được đánh giá.