OpenWebUI/docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs synced 2025-05-19 18:58:41 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Update logging.md

Browse Source
This commit is contained in:
Silentoplayz 2025-04-10 02:30:12 -04:00
parent 21e8eab97e
commit 69c59a0c02
1 changed files with 98 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

147
docs/getting-started/advanced-topics/logging.md
View File

@ -1,70 +1,119 @@
---
sidebar_position: 5
title: "📜 Open WebUI Logging"
title: "📜 Logging in Open WebUI"
---
## Browser Client Logging ##
# Understanding Open WebUI Logging 🪵
Client logging generally occurs via [JavaScript](https://developer.mozilla.org/en-US/docs/Web/API/console/log_static) `console.log()` and can be accessed using the built-in browser-specific developer tools:
Logging is essential for debugging, monitoring, and understanding how Open WebUI is behaving. This guide explains how logging works in both the **browser client** (frontend) and the **application server/backend**.
* Blink
* [Chrome/Chromium](https://developer.chrome.com/docs/devtools/)
* [Edge](https://learn.microsoft.com/en-us/microsoft-edge/devtools-guide-chromium/overview)
* Gecko
* [Firefox](https://firefox-source-docs.mozilla.org/devtools-user/)
* WebKit
* [Safari](https://developer.apple.com/safari/tools/)
## 🖥️ Browser Client Logging (Frontend)
## Application Server/Backend Logging ##
For frontend development and debugging, Open WebUI utilizes standard browser console logging. This means you can see logs directly within your web browser's built-in developer tools.
Logging is an ongoing work-in-progress but some level of control is available using environment variables. [Python Logging](https://docs.python.org/3/howto/logging.html) `log()` and `print()` statements send information to the console. The default level is `INFO`. Ideally, sensitive data will only be exposed with `DEBUG` level.
**How to Access Browser Logs:**
### Logging Levels ###
1. **Open Developer Tools:** In most browsers, you can open developer tools by:
- **Right-clicking** anywhere on the Open WebUI page and selecting "Inspect" or "Inspect Element".
- Pressing **F12** (or Cmd+Opt+I on macOS).
The following [logging levels](https://docs.python.org/3/howto/logging.html#logging-levels) values are supported:
2. **Navigate to the "Console" Tab:** Within the developer tools panel, find and click on the "Console" tab.
| Level | Numeric value |
| ---------- | ------------- |
| `CRITICAL` | 50 |
| `ERROR` | 40 |
| `WARNING` | 30 |
| `INFO` | 20 |
| `DEBUG` | 10 |
| `NOTSET` | 0 |
**Types of Browser Logs:**
### Global ###
Open WebUI primarily uses [JavaScript's](https://developer.mozilla.org/en-US/docs/Web/API/console/log_static) `console.log()` for client-side logging. You'll see various types of messages in the console, including:
The default global log level of `INFO` can be overridden with the `GLOBAL_LOG_LEVEL` environment variable. When set, this executes a [basicConfig](https://docs.python.org/3/library/logging.html#logging.basicConfig) statement with the `force` argument set to *True* within `config.py`. This results in reconfiguration of all attached loggers:
> *If this keyword argument is specified as true, any existing handlers attached to the root logger are removed and closed, before carrying out the configuration as specified by the other arguments.*
- **Informational messages:** General application flow and status.
- **Warnings:** Potential issues or non-critical errors.
- **Errors:** Problems that might be affecting functionality.
The stream uses standard output (`sys.stdout`). In addition to all Open-WebUI `log()` statements, this also affects any imported Python modules that use the Python Logging module `basicConfig` mechanism including [urllib](https://docs.python.org/3/library/urllib.html).
**Browser-Specific Developer Tools:**
For example, to set `DEBUG` logging level as a Docker parameter use:
Different browsers offer slightly different developer tools, but they all provide a console for viewing JavaScript logs. Here are links to documentation for popular browsers:
```
--env GLOBAL_LOG_LEVEL="DEBUG"
```
- **[Blink] Chrome/Chromium (e.g., Chrome, Edge):** [Chrome DevTools Documentation](https://developer.chrome.com/docs/devtools/)
- **[Gecko] Firefox:** [Firefox Developer Tools Documentation](https://firefox-source-docs.mozilla.org/devtools-user/)
- **[WebKit] Safari:** [Safari Developer Tools Documentation](https://developer.apple.com/safari/tools/)
or for Docker Compose put this in the environment section of the docker-compose.yml file (notice the absence of quotation signs):
```
## ⚙️ Application Server/Backend Logging (Python)
The backend of Open WebUI uses Python's built-in `logging` module to record events and information on the server side. These logs are crucial for understanding server behavior, diagnosing errors, and monitoring performance.
**Key Concepts:**
- **Python `logging` Module:** Open WebUI leverages the standard Python `logging` library. If you're familiar with Python logging, you'll find this section straightforward. (For more in-depth information, see the [Python Logging Documentation](https://docs.python.org/3/howto/logging.html#logging-levels)).
- **Console Output:** By default, backend logs are sent to the console (standard output), making them visible in your terminal or Docker container logs.
- **Logging Levels:** Logging levels control the verbosity of the logs. You can configure Open WebUI to show more or less detailed information based on these levels.
### 🚦 Logging Levels Explained
Python logging uses a hierarchy of levels to categorize log messages by severity. Here's a breakdown of the levels, from most to least severe:
| Level | Numeric Value | Description | Use Case |
| ----------- | ------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `CRITICAL` | 50 | **Severe errors** that may lead to application termination. | Catastrophic failures, data corruption. |
| `ERROR` | 40 | **Errors** that indicate problems but the application might still function. | Recoverable errors, failed operations. |
| `WARNING` | 30 | **Potential issues** or unexpected situations that should be investigated. | Deprecation warnings, resource constraints. |
| `INFO` | 20 | **General informational messages** about application operation. | Startup messages, key events, normal operation flow. |
| `DEBUG` | 10 | **Detailed debugging information** for developers. | Function calls, variable values, detailed execution steps. |
| `NOTSET` | 0 | **All messages are logged.** (Usually defaults to `WARNING` if not set). | Useful for capturing absolutely everything, typically for very specific debugging. |
**Default Level:** Open WebUI's default logging level is `INFO`.
### 🌍 Global Logging Level (`GLOBAL_LOG_LEVEL`)
You can change the **global** logging level for the entire Open WebUI backend using the `GLOBAL_LOG_LEVEL` environment variable. This is the most straightforward way to control overall logging verbosity.
**How it Works:**
Setting `GLOBAL_LOG_LEVEL` configures the root logger in Python, affecting all loggers in Open WebUI and potentially some third-party libraries that use [basicConfig](https://docs.python.org/3/library/logging.html#logging.basicConfig). It uses `logging.basicConfig(force=True)`, which means it will override any existing root logger configuration.
**Example: Setting to `DEBUG`**
- **Docker Parameter:**
```bash
--env GLOBAL_LOG_LEVEL="DEBUG"
```
- **Docker Compose (`docker-compose.yml`):**
```yaml
environment:
- GLOBAL_LOG_LEVEL=DEBUG
```
**Impact:** Setting `GLOBAL_LOG_LEVEL` to `DEBUG` will produce the most verbose logs, including detailed information that is helpful for development and troubleshooting. For production environments, `INFO` or `WARNING` might be more appropriate to reduce log volume.
### ⚙️ App/Backend Specific Logging Levels
For more granular control, Open WebUI provides environment variables to set logging levels for specific backend components. Logging is an ongoing work-in-progress, but some level of control is made available using these environment variables. These variables allow you to fine-tune logging for different parts of the application.
**Available Environment Variables:**
| Environment Variable | Component/Module | Description |
| -------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `AUDIO_LOG_LEVEL` | Audio processing | Logging related to audio transcription (faster-whisper), text-to-speech (TTS), and audio handling. |
| `COMFYUI_LOG_LEVEL` | ComfyUI Integration | Logging for interactions with ComfyUI, if you are using this integration. |
| `CONFIG_LOG_LEVEL` | Configuration Management | Logging related to loading and processing Open WebUI configuration files. |
| `DB_LOG_LEVEL` | Database Operations (Peewee) | Logging for database interactions using the Peewee ORM (Object-Relational Mapper). |
| `IMAGES_LOG_LEVEL` | Image Generation (AUTOMATIC1111/Stable Diffusion) | Logging for image generation tasks, especially when using AUTOMATIC1111 Stable Diffusion integration. |
| `MAIN_LOG_LEVEL` | Main Application Execution (Root Logger) | Logging from the main application entry point and root logger. |
| `MODELS_LOG_LEVEL` | Model Management | Logging related to loading, managing, and interacting with language models (LLMs), including authentication. |
| `OLLAMA_LOG_LEVEL` | Ollama Backend Integration | Logging for communication and interaction with the Ollama backend. |
| `OPENAI_LOG_LEVEL` | OpenAI API Integration | Logging for interactions with the OpenAI API (e.g., for models like GPT). |
| `RAG_LOG_LEVEL` | Retrieval-Augmented Generation (RAG) | Logging for the RAG pipeline, including Chroma vector database and Sentence-Transformers. |
| `WEBHOOK_LOG_LEVEL` | Authentication Webhook | Extended logging for authentication webhook functionality. |
**How to Use:**
You can set these environment variables in the same way as `GLOBAL_LOG_LEVEL` (Docker parameters, Docker Compose `environment` section). For example, to get more detailed logging for Ollama interactions, you could set:
```yaml
environment:
- GLOBAL_LOG_LEVEL=DEBUG
- OLLAMA_LOG_LEVEL=DEBUG
```
### App/Backend ###
**Important Note:** Unlike `GLOBAL_LOG_LEVEL`, these app-specific variables might not affect logging from *all* third-party modules. They primarily control logging within Open WebUI's codebase.
Some level of granularity is possible using any of the following combination of variables. Note that `basicConfig` `force` isn't presently used so these statements may only affect Open-WebUI logging and not 3rd party modules.
| Environment Variable | App/Backend |
| -------------------- | ----------------------------------------------------------------- |
| `AUDIO_LOG_LEVEL` | Audio transcription using faster-whisper, TTS etc. |
| `COMFYUI_LOG_LEVEL` | ComfyUI integration handling |
| `CONFIG_LOG_LEVEL` | Configuration handling |
| `DB_LOG_LEVEL` | Internal Peewee Database |
| `IMAGES_LOG_LEVEL` | AUTOMATIC1111 stable diffusion image generation |
| `MAIN_LOG_LEVEL` | Main (root) execution |
| `MODELS_LOG_LEVEL` | LLM model interaction, authentication, etc. |
| `OLLAMA_LOG_LEVEL` | Ollama backend interaction |
| `OPENAI_LOG_LEVEL` | OpenAI interaction |
| `RAG_LOG_LEVEL` | Retrieval-Augmented Generation using Chroma/Sentence-Transformers |
| `WEBHOOK_LOG_LEVEL` | Authentication webhook extended logging |
By understanding and utilizing these logging mechanisms, you can effectively monitor, debug, and gain insights into your Open WebUI instance.