ADORSYS-GIS / ADORSYS-GIS/converse-frontends

[Ticket]: Usage API — expose latency/percentile fields

Đang mở
#294 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
ticket
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

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.