From 923f865fd52b86ec600e29fdbb25a3f33e5b16fe Mon Sep 17 00:00:00 2001 From: Etienne Chabert Date: Fri, 18 Sep 2026 15:29:15 +0200 Subject: [PATCH] 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. --- db_scripts/partition_spend_logs.sql | 8 ++++---- db_scripts/unpartition_spend_logs.sql | 8 ++++---- .../migration.sql | 7 ++++++- .../migration.sql | 14 ++++++++++++++ .../litellm_proxy_extras/schema.prisma | 2 +- litellm/proxy/schema.prisma | 2 +- schema.prisma | 2 +- 7 files changed, 31 insertions(+), 12 deletions(-) create mode 100644 litellm-proxy-extras/litellm_proxy_extras/migrations/20260918120000_spend_logs_api_key_index_cover_spend/migration.sql diff --git a/db_scripts/partition_spend_logs.sql b/db_scripts/partition_spend_logs.sql index c153a67eaec..35aa879da85 100644 --- a/db_scripts/partition_spend_logs.sql +++ b/db_scripts/partition_spend_logs.sql @@ -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. diff --git a/db_scripts/unpartition_spend_logs.sql b/db_scripts/unpartition_spend_logs.sql index 2555eca212b..49f48e973ff 100644 --- a/db_scripts/unpartition_spend_logs.sql +++ b/db_scripts/unpartition_spend_logs.sql @@ -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" diff --git a/litellm-proxy-extras/litellm_proxy_extras/migrations/20260823000000_add_spend_logs_api_key_starttime_index/migration.sql b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260823000000_add_spend_logs_api_key_starttime_index/migration.sql index 9a061aaed43..9d025648f70 100644 --- a/litellm-proxy-extras/litellm_proxy_extras/migrations/20260823000000_add_spend_logs_api_key_starttime_index/migration.sql +++ b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260823000000_add_spend_logs_api_key_starttime_index/migration.sql @@ -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"); diff --git a/litellm-proxy-extras/litellm_proxy_extras/migrations/20260918120000_spend_logs_api_key_index_cover_spend/migration.sql b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260918120000_spend_logs_api_key_index_cover_spend/migration.sql new file mode 100644 index 00000000000..ef66911bed8 --- /dev/null +++ b/litellm-proxy-extras/litellm_proxy_extras/migrations/20260918120000_spend_logs_api_key_index_cover_spend/migration.sql @@ -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"; diff --git a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma index 1894518e51d..873eb49ff36 100644 --- a/litellm-proxy-extras/litellm_proxy_extras/schema.prisma +++ b/litellm-proxy-extras/litellm_proxy_extras/schema.prisma @@ -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 { diff --git a/litellm/proxy/schema.prisma b/litellm/proxy/schema.prisma index 1894518e51d..873eb49ff36 100644 --- a/litellm/proxy/schema.prisma +++ b/litellm/proxy/schema.prisma @@ -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 { diff --git a/schema.prisma b/schema.prisma index 1894518e51d..873eb49ff36 100644 --- a/schema.prisma +++ b/schema.prisma @@ -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 {