diff --git a/docs/my-website/docs/proxy/spend_logs_deletion.md b/docs/my-website/docs/proxy/spend_logs_deletion.md new file mode 100644 index 00000000000..94a6044192c --- /dev/null +++ b/docs/my-website/docs/proxy/spend_logs_deletion.md @@ -0,0 +1,98 @@ +--- +id: spend_logs_deletion +title: Spend Logs Deletion +--- + +# Spend Log Cleanup + +LiteLLM stores a log for every request. Over time, these logs can grow large and slow down your database. The Spend Log Cleanup feature helps manage database size by deleting old logs automatically. + +--- + +## Usage + +### Requirements + +- **Postgres** (for log storage) +- **Redis** *(optional)* — required only if you're running multiple proxy instances and want to enable distributed locking + +### Setup + +Add this to your `proxy_config.yaml` under `general_settings`: + +```yaml title="proxy_config.yaml" +general_settings: + maximum_spend_logs_retention_period: "7d" # Keep logs for 7 days + + # Optional: set how frequently cleanup should run + maximum_spend_logs_retention_interval: "1d" # Run cleanup every day + +litellm_settings: + cache: true + cache_params: + type: redis +``` + +### Configuration Options + +#### `maximum_spend_logs_retention_period` (required) + +How long logs should be kept before deletion. Supported formats: + +- `"7d"` – 7 days +- `"24h"` – 24 hours +- `"60m"` – 60 minutes +- `"3600s"` – 3600 seconds + +#### `maximum_spend_logs_retention_interval` (optional) + +How often the cleanup job should run. Uses the same format as above. If not set, cleanup will run every 24 hours if and only if `maximum_spend_logs_retention_period` is set. + +--- + +## How it works + +### Step 1. Lock Acquisition (Optional with Redis) + +If Redis is enabled, LiteLLM uses it to make sure only one instance runs the cleanup at a time. + +- If the lock is acquired: + - This instance proceeds with cleanup + - Others skip it +- If no lock is present: + - Cleanup still runs (useful for single-node setups) + +![Working of spend log deletions](../../img/spend_log_deletion_working.png) +*Working of spend log deletions* + +--- + +### Step 2. Batch Deletion + +Once cleanup starts: + +- It calculates the cutoff date using the configured retention period +- Deletes logs older than the cutoff in **batches of 1000** +- Adds a short delay between batches to avoid overloading the database + +### Default settings: +- **Batch size**: 1000 logs +- **Max batches per run**: 500 +- **Max deletions per run**: 500,000 logs + +You can change the number of batches using an environment variable: + +```bash +SPEND_LOG_RUN_LOOPS=200 +``` + +This would allow up to 200,000 logs to be deleted in one run. + +![Batch deletion of old logs](../../img/spend_log_deletion_multi_pod.jpg) +*Batch deletion of old logs* + +--- + +## Summary + +Spend Log Cleanup helps keep your database fast by regularly deleting old logs. It’s safe, customizable, and works well for both single-node and multi-node deployments. \ No newline at end of file diff --git a/docs/my-website/docs/proxy/ui_logs.md b/docs/my-website/docs/proxy/ui_logs.md index c6cbbe6e7b7..bca50a2165b 100644 --- a/docs/my-website/docs/proxy/ui_logs.md +++ b/docs/my-website/docs/proxy/ui_logs.md @@ -52,3 +52,30 @@ If you do not want to store spend logs in DB, you can opt out with this setting general_settings: disable_spend_logs: True # Disable writing spend logs to DB ``` + +## Automatically Deleting Old Spend Logs + +If you're storing spend logs, it might be a good idea to delete them regularly to keep the database fast. + +LiteLLM lets you configure this in your `proxy_config.yaml`: + +```yaml +general_settings: + maximum_spend_logs_retention_period: "7d" # Delete logs older than 7 days + + # Optional: how often to run cleanup + maximum_spend_logs_retention_interval: "1d" # Run once per day +``` + +You can control how many logs are deleted per run using this environment variable: + +`SPEND_LOG_RUN_LOOPS=200 # Deletes up to 200,000 logs in one run (batch size = 1000)` + +For detailed architecture and how it works, see [Spend Logs Deletion](../proxy/spend_logs_deletion). + + + + + + + diff --git a/docs/my-website/img/spend_log_deletion_multi_pod.jpg b/docs/my-website/img/spend_log_deletion_multi_pod.jpg new file mode 100644 index 00000000000..52cf22c1a35 Binary files /dev/null and b/docs/my-website/img/spend_log_deletion_multi_pod.jpg differ diff --git a/docs/my-website/img/spend_log_deletion_working.png b/docs/my-website/img/spend_log_deletion_working.png new file mode 100644 index 00000000000..f0dca082611 Binary files /dev/null and b/docs/my-website/img/spend_log_deletion_working.png differ diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js index ccc2f6ccc17..3c51e78b69e 100644 --- a/docs/my-website/sidebars.js +++ b/docs/my-website/sidebars.js @@ -54,7 +54,7 @@ const sidebars = { { type: "category", label: "Architecture", - items: ["proxy/architecture", "proxy/db_info", "proxy/db_deadlocks", "router_architecture", "proxy/user_management_heirarchy", "proxy/jwt_auth_arch", "proxy/image_handling"], + items: ["proxy/architecture", "proxy/db_info", "proxy/db_deadlocks", "router_architecture", "proxy/user_management_heirarchy", "proxy/jwt_auth_arch", "proxy/image_handling", "proxy/spend_logs_deletion"], }, { type: "link", diff --git a/litellm/constants.py b/litellm/constants.py index bedf54561d2..8c72f60bee0 100644 --- a/litellm/constants.py +++ b/litellm/constants.py @@ -618,7 +618,7 @@ LITELLM_PROXY_ADMIN_NAME = "default_user_id" DB_SPEND_UPDATE_JOB_NAME = "db_spend_update_job" PROMETHEUS_EMIT_BUDGET_METRICS_JOB_NAME = "prometheus_emit_budget_metrics" SPEND_LOG_CLEANUP_JOB_NAME = "spend_log_cleanup" -SPEND_LOG_RUN_LOOPS = int(os.getenv("SPEND_LOG_RUN_LOOPS", 100)) +SPEND_LOG_RUN_LOOPS = int(os.getenv("SPEND_LOG_RUN_LOOPS", 500)) DEFAULT_CRON_JOB_LOCK_TTL_SECONDS = int( os.getenv("DEFAULT_CRON_JOB_LOCK_TTL_SECONDS", 60) ) # 1 minute