Skip to content

Commit f7c7814

Browse files
committed
fix(usage): disclose the window a truncated read actually covers
The usage API reads the newest managementUsageMaxReadBytes and applies the 7d/30d/all filter afterwards, so on a busy installation both 30d and Available history summarize the same moving byte tail. A measured case had 30d omitting 73.6% of in-range requests while still labelled 30d, and cumulative totals can decrease as older rows fall out of the window. The response now reports snapshotWindowStart/End: the timestamp bounds of the rows the reader loaded, before range and surface filtering. It describes the READ rather than the query, because truncation is a property of the read. Deliberately not a completeness claim. usage.jsonl is appended when a request completes while each row carries the request start time, so a long-running request can be appended after shorter ones that started later. The oldest loaded timestamp therefore does not bound what the dropped prefix contains, and no derived rangeFullyCovered flag would be sound. The dashboard names the loaded window and downgrades the notice from ok to warn, since a total that omits in-range rows is a caveat. This is a partial mitigation, not the fix #1497 asks for: complete aggregation still needs the rollup work tracked in #1008. Refs #1497, #1008
1 parent 567a6d4 commit f7c7814

12 files changed

Lines changed: 158 additions & 1 deletion

File tree

‎gui/src/i18n/de.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -737,6 +737,7 @@ export const de: Record<TKey, string> = {
737737
"usage.range.all": "Alle",
738738
"usage.range.available": "Verfügbarer Verlauf",
739739
"usage.historyTruncated": "Die Summen beziehen sich nur auf den verfügbaren Verlauf, da ältere Nutzungsdaten nicht geladen wurden.",
740+
"usage.historyTruncatedWindow": "Die Summen umfassen nur die von {start} bis {end} geladene Nutzung. Ältere Einträge überschreiten das Leselimit, daher kann jeder gewählte Zeitraum unvollständig sein.",
740741
"usage.range.30d": "30d",
741742
"usage.range.7d": "7d",
742743
"usage.card.requests": "Anfragen",

‎gui/src/i18n/en.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -768,6 +768,7 @@ export const en = {
768768
"usage.range.all": "All",
769769
"usage.range.available": "Available history",
770770
"usage.historyTruncated": "Totals cover available history only because older usage was not loaded.",
771+
"usage.historyTruncatedWindow": "Totals cover only the usage loaded from {start} to {end}. Older entries exceed the read limit, so any selected range may be incomplete.",
771772
"usage.range.30d": "30d",
772773
"usage.range.7d": "7d",
773774
"usage.card.requests": "Requests",

‎gui/src/i18n/ja.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -726,6 +726,7 @@ export const ja: Record<TKey, string> = {
726726
"usage.range.all": "すべて",
727727
"usage.range.available": "利用可能な履歴",
728728
"usage.historyTruncated": "古い利用履歴が読み込まれていないため、合計は利用可能な履歴のみを対象とします。",
729+
"usage.historyTruncatedWindow": "合計は {start} から {end} までに読み込まれた利用量のみを対象とします。それより古い記録は読み取り上限を超えるため、選択した期間が不完全な場合があります。",
729730
"usage.range.30d": "30日",
730731
"usage.range.7d": "7日",
731732
"usage.card.requests": "リクエスト",

‎gui/src/i18n/ko.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -759,6 +759,7 @@ export const ko: Record<TKey, string> = {
759759
"usage.range.all": "전체",
760760
"usage.range.available": "사용 가능한 기록",
761761
"usage.historyTruncated": "이전 사용 기록을 불러오지 않아 합계는 사용 가능한 기록만 포함합니다.",
762+
"usage.historyTruncatedWindow": "합계는 {start}부터 {end}까지 불러온 사용량만 포함합니다. 그보다 오래된 기록은 읽기 한도를 넘어 선택한 기간이 완전하지 않을 수 있습니다.",
762763
"usage.range.30d": "30일",
763764
"usage.range.7d": "7일",
764765
"usage.card.requests": "요청",

‎gui/src/i18n/ru.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -758,6 +758,7 @@ export const ru: Record<TKey, string> = {
758758
"usage.range.all": "Все",
759759
"usage.range.available": "Доступная история",
760760
"usage.historyTruncated": "Итоги охватывают только доступную историю, поскольку старые данные не загружены.",
761+
"usage.historyTruncatedWindow": "Итоги охватывают только использование, загруженное с {start} по {end}. Более старые записи превышают лимит чтения, поэтому выбранный период может быть неполным.",
761762
"usage.range.30d": "30 дн.",
762763
"usage.range.7d": "7 дн.",
763764
"usage.card.requests": "Запросы",

‎gui/src/i18n/tr.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -765,6 +765,7 @@ export const tr: Record<TKey, string> = {
765765
"usage.range.all": "Tümü",
766766
"usage.range.available": "Mevcut geçmiş",
767767
"usage.historyTruncated": "Toplamlar yalnızca mevcut geçmişi kapsar.",
768+
"usage.historyTruncatedWindow": "Toplamlar yalnızca {start} - {end} aralığında yüklenen kullanımı kapsar. Daha eski kayıtlar okuma sınırını aştığı için seçilen aralık eksik olabilir.",
768769
"usage.range.30d": "30 gün",
769770
"usage.range.7d": "7 gün",
770771
"usage.card.requests": "İstekler",

‎gui/src/i18n/zh-TW.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1586,6 +1586,7 @@ export const zhTW: Record<TKey, string> = {
15861586
"provider.name.volcengineAgentPlan": "Volcengine Ark Agent Plan",
15871587
"usage.range.available": "可用歷史紀錄",
15881588
"usage.historyTruncated": "總計僅涵蓋可用歷史紀錄,因為較舊的用量未被載入。",
1589+
"usage.historyTruncatedWindow": "總計僅涵蓋從 {start} 到 {end} 已載入的用量。更早的紀錄超出讀取上限,因此所選期間可能不完整。",
15891590
"codexAuth.autoSwitchQuotaDesc": "配額:使用率達 {threshold}% 或以上時,下一個請求可能移至用量較低的合格帳號,包括已綁定的任務;Go/Free 僅使用 30 天。",
15901591
"codexAuth.autoSwitchQuotaOffDesc": "基於用量的主動切換已關閉。新增/未綁定分派與故障恢復仍然適用。",
15911592
"codexAuth.autoSwitchRoundRobinDesc": "輪詢分派不使用此閾值;它會繼續輪換新增/未綁定的任務。",

‎gui/src/i18n/zh.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -752,6 +752,7 @@ export const zh: Record<TKey, string> = {
752752
"usage.range.all": "全部",
753753
"usage.range.available": "可用历史",
754754
"usage.historyTruncated": "由于未加载较早的使用记录,合计仅涵盖可用历史。",
755+
"usage.historyTruncatedWindow": "合计仅涵盖从 {start} 到 {end} 已加载的用量。更早的记录超出读取上限,因此所选时间范围可能不完整。",
755756
"usage.range.30d": "30 天",
756757
"usage.range.7d": "7 天",
757758
"usage.card.requests": "请求数",

‎gui/src/pages/Usage.tsx‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,11 @@ interface UsageResponse {
8888
truncatedPrefixBytes: number;
8989
entriesTruncated: boolean;
9090
entriesDropped: number;
91+
// Bounds of the rows the bounded reader loaded, before any range or surface filtering.
92+
// Describes the read, not the query, and is never a completeness claim (#1497).
93+
// Optional because a dashboard can talk to a proxy that predates these fields.
94+
snapshotWindowStart?: number | null;
95+
snapshotWindowEnd?: number | null;
9196
error?: string;
9297
}
9398

@@ -816,7 +821,23 @@ export default function Usage({ apiBase }: { apiBase: string }) {
816821
) : (
817822
<>
818823
{state.showError && <Notice tone="err">{t("usage.loadError")}</Notice>}
819-
{data?.historyTruncated && <Notice tone="ok">{t("usage.historyTruncated")}</Notice>}
824+
{data?.historyTruncated && (
825+
// Naming the loaded window is the point: without it, `30d` and "Available history"
826+
// look identical on a busy installation even though both may cover far less than
827+
// they claim (#1497). `warn` rather than `ok` because a total that silently omits
828+
// in-range rows is a caveat, not a status update.
829+
<Notice tone="warn">
830+
{/* `!= null` rather than `!== null`: an older proxy that predates these fields
831+
omits them entirely, and an undefined bound must fall back to the generic
832+
wording instead of rendering "Invalid Date". */}
833+
{data.snapshotWindowStart != null && data.snapshotWindowEnd != null
834+
? t("usage.historyTruncatedWindow", {
835+
start: new Date(data.snapshotWindowStart).toLocaleString(),
836+
end: new Date(data.snapshotWindowEnd).toLocaleString(),
837+
})
838+
: t("usage.historyTruncated")}
839+
</Notice>
840+
)}
820841
<UsageWorkspaceBody
821842
data={data}
822843
heatmap={heatmap}

‎gui/tests/usage-layout.test.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ test("usage workspace i18n keys exist in every locale", async () => {
6868
expect(dict).toContain('"usage.workspace.report":');
6969
expect(dict).toContain('"usage.range.available":');
7070
expect(dict).toContain('"usage.historyTruncated":');
71+
expect(dict).toContain('"usage.historyTruncatedWindow":');
7172
expect(dict).toContain('"api.attribution.totalRequestsAvailable":');
7273
}
7374
});
@@ -143,6 +144,19 @@ test("Usage renders Available history and a persistent qualification when histor
143144
}
144145
});
145146

147+
test("Usage names the loaded window when history is truncated", async () => {
148+
const page = await Bun.file(new URL("../src/pages/Usage.tsx", import.meta.url)).text();
149+
150+
// #1497: when the proxy reports the window it actually loaded, the notice must name that
151+
// window instead of the generic wording — otherwise `30d` and "Available history" stay
152+
// indistinguishable on a busy installation. `!= null` keeps an older proxy that omits the
153+
// fields on the generic string rather than rendering "Invalid Date".
154+
expect(page).toContain("usage.historyTruncatedWindow");
155+
expect(page).toContain("data.snapshotWindowStart != null && data.snapshotWindowEnd != null");
156+
// A total that silently omits in-range rows is a caveat, not a status update.
157+
expect(page).toContain('<Notice tone="warn">');
158+
});
159+
146160
test("Usage source marks keep brand colors and invert only the monochrome Grok mark", async () => {
147161
const page = await Bun.file(new URL("../src/pages/Usage.tsx", import.meta.url)).text();
148162
const css = await Bun.file(new URL("../src/styles.css", import.meta.url)).text();

0 commit comments

Comments
 (0)