perf(spend_tracking): cover spend in the LiteLLM_SpendLogs api_key index

The per-key window aggregates that the (api_key, startTime) index from
#37983 was added for all read SUM(spend) WHERE api_key = ... AND
"startTime" >= ... (budget-window reseed, BudgetWindowSpend seeding, the
spend-logs fallback). api_key has ~zero physical correlation, so a key's
rows sit about one per heap page and the plain index still pays one heap
page per matching row just to read spend. Carrying spend in the index
makes those sums index-only scans.

spend is a trailing key column rather than INCLUDE (spend) because
Prisma's @@index cannot express INCLUDE. Postgres answers the same query
from either shape with an identical plan and index size.

20260823000000 has not reached a stable release yet, so it now builds the
covering index directly: installs upgrading from a stable release pay for
one index build on LiteLLM_SpendLogs, not two. 20260918120000 moves
installs that already applied the original file (v1.103.0-dev.2) over,
creating the covering index before dropping the old one, and is a no-op
everywhere else. The partition runbooks carry the new name and columns.

Verified on Postgres 18 with `prisma migrate deploy`:
  * stable upgrade: both migrations apply, one covering index, no drift
  * dev.2 upgrade: deploy accepts the edited 20260823000000, the new
    migration swaps the plain index for the covering one, no drift
  * partition/unpartition runbooks keep the covering index on the parent,
    the DEFAULT partition, and the round-tripped table

1.5M rows / 10k keys / 64-char hashed keys: 88 -> 8 buffers per key
aggregate, index 151 MB -> 163 MB.
This commit is contained in:
Etienne Chabert 2026-09-18 15:29:15 +02:00
parent 8fc9c46d1a
commit 923f865fd5
No known key found for this signature in database
7 changed files with 31 additions and 12 deletions

View file

@ -53,8 +53,8 @@ ALTER INDEX IF EXISTS "LiteLLM_SpendLogs_end_user_idx"
RENAME TO "LiteLLM_SpendLogs_legacy_end_user_idx";
ALTER INDEX IF EXISTS "LiteLLM_SpendLogs_session_id_idx"
RENAME TO "LiteLLM_SpendLogs_legacy_session_id_idx";
ALTER INDEX IF EXISTS "LiteLLM_SpendLogs_api_key_startTime_idx"
RENAME TO "LiteLLM_SpendLogs_legacy_api_key_startTime_idx";
ALTER INDEX IF EXISTS "LiteLLM_SpendLogs_api_key_startTime_spend_idx"
RENAME TO "LiteLLM_SpendLogs_legacy_api_key_startTime_spend_idx";
CREATE TABLE "LiteLLM_SpendLogs" (
LIKE "LiteLLM_SpendLogs_legacy" INCLUDING DEFAULTS INCLUDING GENERATED
@ -80,8 +80,8 @@ CREATE INDEX IF NOT EXISTS "LiteLLM_SpendLogs_end_user_idx"
CREATE INDEX IF NOT EXISTS "LiteLLM_SpendLogs_session_id_idx"
ON "LiteLLM_SpendLogs" ("session_id");
CREATE INDEX IF NOT EXISTS "LiteLLM_SpendLogs_api_key_startTime_idx"
ON "LiteLLM_SpendLogs" ("api_key", "startTime");
CREATE INDEX IF NOT EXISTS "LiteLLM_SpendLogs_api_key_startTime_spend_idx"
ON "LiteLLM_SpendLogs" ("api_key", "startTime", "spend");
-- Safety net: any row whose startTime has no explicit partition lands here so
-- writes never fail. The cleanup job never drops the DEFAULT partition.

View file

@ -40,8 +40,8 @@ ALTER INDEX IF EXISTS "LiteLLM_SpendLogs_end_user_idx"
RENAME TO "LiteLLM_SpendLogs_partitioned_end_user_idx";
ALTER INDEX IF EXISTS "LiteLLM_SpendLogs_session_id_idx"
RENAME TO "LiteLLM_SpendLogs_partitioned_session_id_idx";
ALTER INDEX IF EXISTS "LiteLLM_SpendLogs_api_key_startTime_idx"
RENAME TO "LiteLLM_SpendLogs_partitioned_api_key_startTime_idx";
ALTER INDEX IF EXISTS "LiteLLM_SpendLogs_api_key_startTime_spend_idx"
RENAME TO "LiteLLM_SpendLogs_partitioned_api_key_startTime_spend_idx";
CREATE TABLE "LiteLLM_SpendLogs" (
LIKE "LiteLLM_SpendLogs_partitioned" INCLUDING DEFAULTS INCLUDING GENERATED
@ -62,8 +62,8 @@ CREATE INDEX IF NOT EXISTS "LiteLLM_SpendLogs_end_user_idx"
CREATE INDEX IF NOT EXISTS "LiteLLM_SpendLogs_session_id_idx"
ON "LiteLLM_SpendLogs" ("session_id");
CREATE INDEX IF NOT EXISTS "LiteLLM_SpendLogs_api_key_startTime_idx"
ON "LiteLLM_SpendLogs" ("api_key", "startTime");
CREATE INDEX IF NOT EXISTS "LiteLLM_SpendLogs_api_key_startTime_spend_idx"
ON "LiteLLM_SpendLogs" ("api_key", "startTime", "spend");
INSERT INTO "LiteLLM_SpendLogs"
SELECT * FROM "LiteLLM_SpendLogs_partitioned"

View file

@ -1,2 +1,7 @@
-- CreateIndex
CREATE INDEX IF NOT EXISTS "LiteLLM_SpendLogs_api_key_startTime_idx" ON "LiteLLM_SpendLogs"("api_key", "startTime");
-- Builds the covering (api_key, startTime, spend) index directly, so installs
-- that have not applied this migration yet pay for one index build on
-- LiteLLM_SpendLogs rather than two. Installs that already applied the earlier
-- (api_key, startTime) version of this file are moved over by
-- 20260918120000_spend_logs_api_key_index_cover_spend.
CREATE INDEX IF NOT EXISTS "LiteLLM_SpendLogs_api_key_startTime_spend_idx" ON "LiteLLM_SpendLogs"("api_key", "startTime", "spend");

View file

@ -0,0 +1,14 @@
-- Replaces "LiteLLM_SpendLogs_api_key_startTime_idx" with an index that also
-- carries "spend", so per-key window sums (SUM(spend) WHERE api_key = ... AND
-- "startTime" >= ...) run as index-only scans instead of fetching one heap page
-- per matching row. "spend" is a trailing key column rather than an INCLUDE
-- column because Prisma's @@index cannot express INCLUDE.
--
-- No-op where 20260823000000 already built the covering index. The new index is
-- built before the old one is dropped, so reads keep an index throughout.
-- CreateIndex
CREATE INDEX IF NOT EXISTS "LiteLLM_SpendLogs_api_key_startTime_spend_idx" ON "LiteLLM_SpendLogs"("api_key", "startTime", "spend");
-- DropIndex
DROP INDEX IF EXISTS "LiteLLM_SpendLogs_api_key_startTime_idx";

View file

@ -678,7 +678,7 @@ model LiteLLM_SpendLogs {
@@index([end_user])
@@index([session_id])
@@index([litellm_call_id])
@@index([api_key, startTime])
@@index([api_key, startTime, spend])
}
model LiteLLM_BudgetWindowSpend {

View file

@ -678,7 +678,7 @@ model LiteLLM_SpendLogs {
@@index([end_user])
@@index([session_id])
@@index([litellm_call_id])
@@index([api_key, startTime])
@@index([api_key, startTime, spend])
}
model LiteLLM_BudgetWindowSpend {

View file

@ -678,7 +678,7 @@ model LiteLLM_SpendLogs {
@@index([end_user])
@@index([session_id])
@@index([litellm_call_id])
@@index([api_key, startTime])
@@index([api_key, startTime, spend])
}
model LiteLLM_BudgetWindowSpend {