perf: build debug log messages lazily so disabled debug logs cost nothing (#27834)

GLOBAL_LOG_LEVEL defaults to INFO, so every log.debug(...) in the backend is discarded, but the message is built first: 187 call sites interpolate their payload into an f-string before the logging call runs, so the work happens on every request and the result is thrown away. The worst one sits in process_chat_payload and stringifies the whole request body, full conversation history included, once per chat completion.

That one line with DEBUG disabled, CPython 3.12:

| conversation | payload | before   | after   |
| ------------ | ------- | -------- | ------- |
| 4 messages   | 1.2 kB  | 3.4 us   | 0.07 us |
| 20 messages  | 17 kB   | 24.8 us  | 0.07 us |
| 60 messages  | 123 kB  | 216.6 us | 0.07 us |

The lazy form log.debug('form_data: %s', form_data) hands the payload to record.getMessage(), which the InterceptHandler only reaches once a record has passed the level check. With DEBUG enabled the emitted lines are byte-identical, f'{x=}' sites included: those map to %r. MistralLoader._debug_log callers get the same treatment, since that wrapper already forwards *args.

backend/open_webui/retrieval/loaders/mineru.py

@@ -98,7 +98,7 @@ class MinerULoader:
                 files = {'files': (filename, f, 'application/octet-stream')}
 
                 log.info(f'Sending file to MinerU Local API: {filename}')
-                log.debug(f'Local API parameters: {form_data}')
+                log.debug('Local API parameters: %s', form_data)
 
                 response = requests.post(
                     f'{self.api_url}/file_parse',
@@ -233,7 +233,7 @@ class MinerULoader:
             request_body['files'][0]['page_ranges'] = self.page_ranges
 
         log.info(f'Requesting upload URL for: {filename}')
-        log.debug(f'Cloud API request body: {request_body}')
+        log.debug('Cloud API request body: %s', request_body)
 
         try:
             response = requests.post(

backend/open_webui/retrieval/loaders/mistral.py

@@ -338,7 +338,7 @@ class MistralLoader:
         headers = {**self.headers, 'Accept': 'application/json'}
 
         async def url_request():
-            self._debug_log(f'Getting signed URL for file ID: {file_id}')
+            self._debug_log('Getting signed URL for file ID: %s', file_id)
             async with session.get(
                 url,
                 headers=headers,
@@ -450,7 +450,7 @@ class MistralLoader:
         try:
 
             async def delete_request():
-                self._debug_log(f'Deleting file ID: {file_id}')
+                self._debug_log('Deleting file ID: %s', file_id)
                 async with session.delete(
                     url=f'{self.base_url}/files/{file_id}',
                     headers=self.headers,
@@ -460,7 +460,7 @@ class MistralLoader:
                     return await self._handle_response_async(response)
 
             await self._retry_request_async(delete_request)
-            self._debug_log(f'File {file_id} deleted successfully')
+            self._debug_log('File %s deleted successfully', file_id)
 
         except Exception as e:
             # Don't fail the entire process if cleanup fails
@@ -519,7 +519,7 @@ class MistralLoader:
             if page_content is None or page_index is None:
                 skipped_pages += 1
                 self._debug_log(
-                    f"Skipping page due to missing 'markdown' or 'index'. Data keys: {list(page_data.keys())}"
+                    "Skipping page due to missing 'markdown' or 'index'. Data keys: %s", list(page_data.keys())
                 )
                 continue
 
@@ -531,7 +531,7 @@ class MistralLoader:
 
             if not cleaned_content:
                 skipped_pages += 1
-                self._debug_log(f'Skipping empty page {page_index}')
+                self._debug_log('Skipping empty page %s', page_index)
                 continue
 
             # Create document with optimized metadata

backend/open_webui/retrieval/loaders/youtube.py

@@ -90,7 +90,7 @@ class YoutubeLoader:
 
         if self.proxy_url:
             youtube_proxies = GenericProxyConfig(http_url=self.proxy_url, https_url=self.proxy_url)
-            log.debug(f'Using proxy URL: {self.proxy_url[:14]}...')
+            log.debug('Using proxy URL: %s...', self.proxy_url[:14])
         else:
             youtube_proxies = None
 
@@ -106,23 +106,23 @@ class YoutubeLoader:
             try:
                 transcript = transcript_list.find_transcript([lang])
                 if transcript.is_generated:
-                    log.debug(f"Found generated transcript for language '{lang}'")
+                    log.debug("Found generated transcript for language '%s'", lang)
                     try:
                         transcript = transcript_list.find_manually_created_transcript([lang])
-                        log.debug(f"Found manual transcript for language '{lang}'")
+                        log.debug("Found manual transcript for language '%s'", lang)
                     except NoTranscriptFound:
-                        log.debug(f"No manual transcript found for language '{lang}', using generated")
+                        log.debug("No manual transcript found for language '%s', using generated", lang)
                         pass
 
-                log.debug(f"Found transcript for language '{lang}'")
+                log.debug("Found transcript for language '%s'", lang)
                 try:
                     transcript_pieces: List[Dict[str, Any]] = transcript.fetch()
                 except ParseError:
-                    log.debug(f"Empty or invalid transcript for language '{lang}'")
+                    log.debug("Empty or invalid transcript for language '%s'", lang)
                     continue
 
                 if not transcript_pieces:
-                    log.debug(f"Empty transcript for language '{lang}'")
+                    log.debug("Empty transcript for language '%s'", lang)
                     continue
 
                 transcript_text = ' '.join(
@@ -135,7 +135,7 @@ class YoutubeLoader:
                 )
                 return [Document(page_content=transcript_text, metadata=self._metadata)]
             except NoTranscriptFound:
-                log.debug(f"No transcript found for language '{lang}'")
+                log.debug("No transcript found for language '%s'", lang)
                 continue
             except Exception as e:
                 log.info(f"Error finding transcript for language '{lang}'")

backend/open_webui/retrieval/utils.py

@@ -310,7 +310,7 @@ class VectorSearchRetriever(BaseRetriever):
 
 def query_doc(collection_name: str, query_embedding: list[float], k: int, user: UserModel = None):
     try:
-        log.debug(f'query_doc:doc {collection_name}')
+        log.debug('query_doc:doc %s', collection_name)
         result = VECTOR_DB_CLIENT.search(
             collection_name=collection_name,
             vectors=[query_embedding],
@@ -328,7 +328,7 @@ def query_doc(collection_name: str, query_embedding: list[float], k: int, user:
 
 def get_doc(collection_name: str, user: UserModel = None):
     try:
-        log.debug(f'get_doc:doc {collection_name}')
+        log.debug('get_doc:doc %s', collection_name)
         result = VECTOR_DB_CLIENT.get(collection_name=collection_name)
 
         if result:
@@ -457,7 +457,7 @@ async def query_doc_with_native_hybrid_search(
             'metadatas': [metadatas],
         }
     except Exception as e:
-        log.debug(f'Native hybrid search failed for {collection_name}, falling back to legacy hybrid search: {e}')
+        log.debug('Native hybrid search failed for %s, falling back to legacy hybrid search: %s', collection_name, e)
         return None
 
 
@@ -510,7 +510,7 @@ async def query_doc_with_hybrid_search(
             log.warning(f'query_doc_with_hybrid_search:no_docs {collection_name}')
             return {'documents': [], 'metadatas': [], 'distances': []}
 
-        log.debug(f'query_doc_with_hybrid_search:doc {collection_name}')
+        log.debug('query_doc_with_hybrid_search:doc %s', collection_name)
 
         original_texts = collection_result.documents[0]
         bm25_metadatas = [
@@ -707,7 +707,7 @@ async def query_collection(
                 enable_enriched_texts=config.get('rag.enable_hybrid_search_enriched_texts'),
             )
         except Exception as e:
-            log.debug(f'Hybrid search failed, falling back to vector search: {e}')
+            log.debug('Hybrid search failed, falling back to vector search: %s', e)
 
     results = []
     error = False
@@ -736,7 +736,7 @@ async def query_collection(
 
     # Generate all query embeddings (in one call)
     query_embeddings = await embedding_function(queries, prefix=RAG_EMBEDDING_QUERY_PREFIX)
-    log.debug(f'query_collection: processing {len(queries)} queries across {len(collection_names)} collections')
+    log.debug('query_collection: processing %s queries across %s collections', len(queries), len(collection_names))
 
     task_results = await asyncio.gather(
         *[
@@ -866,7 +866,7 @@ def generate_openai_batch_embeddings(
     prefix: str = None,
     user: UserModel = None,
 ) -> list[list[float]]:
-    log.debug(f'generate_openai_batch_embeddings:model {model} batch size: {len(texts)}')
+    log.debug('generate_openai_batch_embeddings:model %s batch size: %s', model, len(texts))
     json_data = {'input': texts, 'model': model}
     if isinstance(RAG_EMBEDDING_PREFIX_FIELD_NAME, str) and isinstance(prefix, str):
         json_data[RAG_EMBEDDING_PREFIX_FIELD_NAME] = prefix
@@ -899,7 +899,7 @@ async def agenerate_openai_batch_embeddings(
     prefix: str = None,
     user: UserModel = None,
 ) -> list[list[float]]:
-    log.debug(f'agenerate_openai_batch_embeddings:model {model} batch size: {len(texts)}')
+    log.debug('agenerate_openai_batch_embeddings:model %s batch size: %s', model, len(texts))
     form_data = {'input': texts, 'model': model}
     if isinstance(RAG_EMBEDDING_PREFIX_FIELD_NAME, str) and isinstance(prefix, str):
         form_data[RAG_EMBEDDING_PREFIX_FIELD_NAME] = prefix
@@ -937,7 +937,7 @@ def generate_azure_openai_batch_embeddings(
     prefix: str = None,
     user: UserModel = None,
 ) -> list[list[float]]:
-    log.debug(f'generate_azure_openai_batch_embeddings:deployment {model} batch size: {len(texts)}')
+    log.debug('generate_azure_openai_batch_embeddings:deployment %s batch size: %s', model, len(texts))
     json_data = {'input': texts}
     if isinstance(RAG_EMBEDDING_PREFIX_FIELD_NAME, str) and isinstance(prefix, str):
         json_data[RAG_EMBEDDING_PREFIX_FIELD_NAME] = prefix
@@ -979,7 +979,7 @@ async def agenerate_azure_openai_batch_embeddings(
     prefix: str = None,
     user: UserModel = None,
 ) -> list[list[float]]:
-    log.debug(f'agenerate_azure_openai_batch_embeddings:deployment {model} batch size: {len(texts)}')
+    log.debug('agenerate_azure_openai_batch_embeddings:deployment %s batch size: %s', model, len(texts))
     form_data = {'input': texts}
     if isinstance(RAG_EMBEDDING_PREFIX_FIELD_NAME, str) and isinstance(prefix, str):
         form_data[RAG_EMBEDDING_PREFIX_FIELD_NAME] = prefix
@@ -1018,7 +1018,7 @@ def generate_ollama_batch_embeddings(
     prefix: str = None,
     user: UserModel = None,
 ) -> list[list[float]]:
-    log.debug(f'generate_ollama_batch_embeddings:model {model} batch size: {len(texts)}')
+    log.debug('generate_ollama_batch_embeddings:model %s batch size: %s', model, len(texts))
     json_data = {'input': texts, 'model': model, 'truncate': True}
     if isinstance(RAG_EMBEDDING_PREFIX_FIELD_NAME, str) and isinstance(prefix, str):
         json_data[RAG_EMBEDDING_PREFIX_FIELD_NAME] = prefix
@@ -1054,7 +1054,7 @@ async def agenerate_ollama_batch_embeddings(
     prefix: str = None,
     user: UserModel = None,
 ) -> list[list[float]]:
-    log.debug(f'agenerate_ollama_batch_embeddings:model {model} batch size: {len(texts)}')
+    log.debug('agenerate_ollama_batch_embeddings:model %s batch size: %s', model, len(texts))
     form_data = {'input': texts, 'model': model, 'truncate': True}
     if isinstance(RAG_EMBEDDING_PREFIX_FIELD_NAME, str) and isinstance(prefix, str):
         form_data[RAG_EMBEDDING_PREFIX_FIELD_NAME] = prefix
@@ -1138,7 +1138,7 @@ def get_embedding_function(
                 batches = [query[i : i + embedding_batch_size] for i in range(0, len(query), embedding_batch_size)]
 
                 if enable_async:
-                    log.debug(f'generate_multiple_async: Processing {len(batches)} batches in parallel')
+                    log.debug('generate_multiple_async: Processing %s batches in parallel', len(batches))
                     # Use semaphore to limit concurrent embedding API requests
                     # 0 = unlimited (no semaphore)
                     if concurrent_requests:
@@ -1153,7 +1153,7 @@ def get_embedding_function(
                         tasks = [embedding_function(batch, prefix=prefix, user=user) for batch in batches]
                     batch_results = await asyncio.gather(*tasks)
                 else:
-                    log.debug(f'generate_multiple_async: Processing {len(batches)} batches sequentially')
+                    log.debug('generate_multiple_async: Processing %s batches sequentially', len(batches))
                     batch_results = []
                     for batch in batches:
                         batch_results.append(await embedding_function(batch, prefix=prefix, user=user))
@@ -1166,7 +1166,9 @@ def get_embedding_function(
                     embeddings.extend(batch_embeddings)
 
                 log.debug(
-                    f'generate_multiple_async: Generated {len(embeddings)} embeddings from {len(batches)} parallel batches'
+                    'generate_multiple_async: Generated %s embeddings from %s parallel batches',
+                    len(embeddings),
+                    len(batches),
                 )
                 return embeddings
             else:
@@ -1606,14 +1608,14 @@ async def get_sources_from_items(
         if query_result is None and collection_names:
             collection_names = set(collection_names).difference(extracted_collections)
             if not collection_names:
-                log.debug(f'skipping {item} as it has already been extracted')
+                log.debug('skipping %s as it has already been extracted', item)
                 continue
 
             # Filter out collections the user cannot read
             if user and (item.get('type'), item.get('id')) not in folder_items:
                 collection_names = await filter_accessible_collections(collection_names, user)
                 if not collection_names:
-                    log.debug(f'access denied for all collections in item {item}')
+                    log.debug('access denied for all collections in item %s', item)
                     continue
 
             try:
@@ -1672,8 +1674,8 @@ def get_model_path(model: str, update_model: bool = False):
         'local_files_only': local_files_only,
     }
 
-    log.debug(f'model: {model}')
-    log.debug(f'snapshot_kwargs: {snapshot_kwargs}')
+    log.debug('model: %s', model)
+    log.debug('snapshot_kwargs: %s', snapshot_kwargs)
 
     # Inspiration from upstream sentence_transformers
     if os.path.exists(model) or ('\\' in model or model.count('/') > 1) and local_files_only:
@@ -1688,7 +1690,7 @@ def get_model_path(model: str, update_model: bool = False):
     # Attempt to query the huggingface_hub library to determine the local path and/or to update
     try:
         model_repo_path = snapshot_download(**snapshot_kwargs)
-        log.debug(f'model_repo_path: {model_repo_path}')
+        log.debug('model_repo_path: %s', model_repo_path)
         return model_repo_path
     except Exception as e:
         log.exception(f'Cannot determine model snapshot path: {e}')

backend/open_webui/retrieval/vector/dbs/chroma.py

@@ -182,7 +182,7 @@ class ChromaClient(VectorDBBase):
                     collection.delete(where=filter)
         except Exception as e:
             # If collection doesn't exist, that's fine - nothing to delete
-            log.debug(f'Attempted to delete from non-existent collection {collection_name}. Ignoring.')
+            log.debug('Attempted to delete from non-existent collection %s. Ignoring.', collection_name)
             pass
 
     def reset(self):

backend/open_webui/retrieval/vector/dbs/milvus.py

@@ -242,7 +242,7 @@ class MilvusClient(VectorDBBase):
                     break
                 all_results.extend(batch)
 
-            log.debug(f'Total results from query: {len(all_results)}')
+            log.debug('Total results from query: %s', len(all_results))
             return self._result_to_get_result([all_results] if all_results else [[]])
 
         except Exception as e:

backend/open_webui/retrieval/vector/dbs/pinecone.py

@@ -274,7 +274,7 @@ class PineconeClient(VectorDBBase):
                 log.error(f'Error inserting batch: {e}')
                 raise
         elapsed = time.time() - start_time
-        log.debug(f'Insert of {len(points)} vectors took {elapsed:.2f} seconds')
+        log.debug('Insert of %s vectors took %.2f seconds', len(points), elapsed)
         log.info(
             f"Successfully inserted {len(points)} vectors in parallel batches into '{collection_name_with_prefix}'"
         )
@@ -303,7 +303,7 @@ class PineconeClient(VectorDBBase):
                 log.error(f'Error upserting batch: {e}')
                 raise
         elapsed = time.time() - start_time
-        log.debug(f'Upsert of {len(points)} vectors took {elapsed:.2f} seconds')
+        log.debug('Upsert of %s vectors took %.2f seconds', len(points), elapsed)
         log.info(
             f"Successfully upserted {len(points)} vectors in parallel batches into '{collection_name_with_prefix}'"
         )
@@ -474,7 +474,9 @@ class PineconeClient(VectorDBBase):
                     # Note: When deleting by ID, we can't filter by collection_name
                     # This is a limitation of Pinecone - be careful with ID uniqueness
                     self.index.delete(ids=batch_ids)
-                    log.debug(f"Deleted batch of {len(batch_ids)} vectors by ID from '{collection_name_with_prefix}'")
+                    log.debug(
+                        "Deleted batch of %s vectors by ID from '%s'", len(batch_ids), collection_name_with_prefix
+                    )
                 log.info(f"Successfully deleted {len(ids)} vectors by ID from '{collection_name_with_prefix}'")
 
             elif filter:

backend/open_webui/retrieval/vector/dbs/qdrant_multitenancy.py

@@ -224,7 +224,7 @@ class QdrantClient(VectorDBBase):
 
         mt_collection, tenant_id = self._get_collection_and_tenant_id(collection_name)
         if not self.client.collection_exists(collection_name=mt_collection):
-            log.debug(f"Collection {mt_collection} doesn't exist, nothing to delete")
+            log.debug("Collection %s doesn't exist, nothing to delete", mt_collection)
             return None
 
         must_conditions = [_tenant_filter(tenant_id)]
@@ -255,7 +255,7 @@ class QdrantClient(VectorDBBase):
             return None
         mt_collection, tenant_id = self._get_collection_and_tenant_id(collection_name)
         if not self.client.collection_exists(collection_name=mt_collection):
-            log.debug(f"Collection {mt_collection} doesn't exist, search returns None")
+            log.debug("Collection %s doesn't exist, search returns None", mt_collection)
             return None
 
         tenant_filter = _tenant_filter(tenant_id)
@@ -281,7 +281,7 @@ class QdrantClient(VectorDBBase):
             return None
         mt_collection, tenant_id = self._get_collection_and_tenant_id(collection_name)
         if not self.client.collection_exists(collection_name=mt_collection):
-            log.debug(f"Collection {mt_collection} doesn't exist, query returns None")
+            log.debug("Collection %s doesn't exist, query returns None", mt_collection)
             return None
         if limit is None:
             limit = NO_LIMIT
@@ -303,7 +303,7 @@ class QdrantClient(VectorDBBase):
             return None
         mt_collection, tenant_id = self._get_collection_and_tenant_id(collection_name)
         if not self.client.collection_exists(collection_name=mt_collection):
-            log.debug(f"Collection {mt_collection} doesn't exist, get returns None")
+            log.debug("Collection %s doesn't exist, get returns None", mt_collection)
             return None
         tenant_filter = _tenant_filter(tenant_id)
         points = self.client.scroll(
@@ -350,7 +350,7 @@ class QdrantClient(VectorDBBase):
             return None
         mt_collection, tenant_id = self._get_collection_and_tenant_id(collection_name)
         if not self.client.collection_exists(collection_name=mt_collection):
-            log.debug(f"Collection {mt_collection} doesn't exist, nothing to delete")
+            log.debug("Collection %s doesn't exist, nothing to delete", mt_collection)
             return None
         self.client.delete(
             collection_name=mt_collection,

backend/open_webui/retrieval/vector/dbs/s3vector.py

@@ -54,7 +54,7 @@ class S3VectorClient(VectorDBBase):
         Create a new index in the S3 vector bucket for the given collection if it does not exist.
         """
         if self.has_collection(index_name):
-            log.debug(f"Index '{index_name}' already exists, skipping creation")
+            log.debug("Index '%s' already exists, skipping creation", index_name)
             return
 
         try:
@@ -310,7 +310,7 @@ class S3VectorClient(VectorDBBase):
 
             # Process each query vector
             for i, query_vector in enumerate(vectors):
-                log.debug(f'Processing query vector {i + 1}/{len(vectors)}')
+                log.debug('Processing query vector %s/%s', i + 1, len(vectors))
 
                 # Prepare the query vector in S3 Vector format
                 query_vector_dict = {'float32': [float(x) for x in query_vector]}
@@ -521,7 +521,7 @@ class S3VectorClient(VectorDBBase):
                             )
 
                         # Log the actual content for debugging
-                        log.debug(f'Document text preview (first 200 chars): {str(document_text)[:200]}')
+                        log.debug('Document text preview (first 200 chars): %s', str(document_text)[:200])
                     else:
                         document_text = vector_id
 

backend/open_webui/retrieval/vector/dbs/valkey.py

@@ -390,7 +390,7 @@ class ValkeyClient(VectorDBBase):
             )
         except g['RequestError'] as e:
             if 'already exists' in str(e).lower():
-                log.debug(f'Index {index_name} already exists, skipping creation.')
+                log.debug('Index %s already exists, skipping creation.', index_name)
             else:
                 raise
 
@@ -458,7 +458,7 @@ class ValkeyClient(VectorDBBase):
             self._g['glide_ft'].dropindex(self.client, index_name)
             log.info(f'Dropped index {index_name}')
         except self._g['RequestError'] as e:
-            log.debug(f'Could not drop index {index_name}: {e}')
+            log.debug('Could not drop index %s: %s', index_name, e)
 
         self._delete_keys_by_prefix(self._key_prefix(collection_name))
 
@@ -492,7 +492,7 @@ class ValkeyClient(VectorDBBase):
             }
             self.batch_client.hset(self._item_key(collection_name, item['id']), mapping)
 
-        log.debug(f'Inserted {len(items)} items into collection {collection_name}')
+        log.debug('Inserted %s items into collection %s', len(items), collection_name)
 
     def upsert(self, collection_name: str, items: list[VectorItem]):
         self.insert(collection_name, items)

backend/open_webui/retrieval/web/utils.py

@@ -155,7 +155,7 @@ def safe_validate_urls(url: Sequence[str]) -> Sequence[str]:
             if validate_url(u):
                 valid_urls.append(u)
         except Exception as e:
-            log.debug(f'Invalid URL {u}: {str(e)}')
+            log.debug('Invalid URL %s: %s', u, e)
             continue
     return valid_urls
 

backend/open_webui/retrieval/web/yacy.py

@@ -53,7 +53,7 @@ def search_yacy(
         # Strip all query parameters from the URL
         query_url = query_url.rstrip('/') + '/yacysearch.json'
 
-    log.debug(f'searching {query_url}')
+    log.debug('searching %s', query_url)
 
     response = requests.get(
         query_url,