feat: Add DOCLING_SERVE_LOG_LEVEL environment variable support (#482)

Signed-off-by: Michele Dolfi <dol@zurich.ibm.com>

.env.example

@@ -1,3 +1,6 @@
 TESSDATA_PREFIX=/usr/share/tesseract/tessdata/
 UVICORN_WORKERS=2
-UVICORN_RELOAD=True
+UVICORN_RELOAD=True
+
+# Logging configuration (case-insensitive)
+# DOCLING_SERVE_LOG_LEVEL=WARNING  # Options: WARNING, INFO, DEBUG (or warning, info, debug)

docling_serve/__main__.py

@@ -66,12 +66,21 @@ def callback(
         ),
     ] = 0,
 ) -> None:
-    if verbose == 0:
+    # Priority: CLI flag > ENV variable > default (WARNING)
+    if verbose > 0:
+        # CLI flag takes precedence
+        if verbose == 1:
+            logging.basicConfig(level=logging.INFO)
+        elif verbose >= 2:
+            logging.basicConfig(level=logging.DEBUG)
+    elif docling_serve_settings.log_level:
+        # Use ENV variable if CLI flag not provided
+        logging.basicConfig(
+            level=getattr(logging, docling_serve_settings.log_level.value)
+        )
+    else:
+        # Default to WARNING
         logging.basicConfig(level=logging.WARNING)
-    elif verbose == 1:
-        logging.basicConfig(level=logging.INFO)
-    elif verbose == 2:
-        logging.basicConfig(level=logging.DEBUG)
 
 
 def _run(
@@ -381,6 +390,14 @@ def rq_worker() -> Any:
     from docling_serve.rq_instrumentation import setup_rq_worker_instrumentation
     from docling_serve.rq_worker_instrumented import InstrumentedRQWorker
 
+    # Configure logging for RQ worker
+    if docling_serve_settings.log_level:
+        logging.basicConfig(
+            level=getattr(logging, docling_serve_settings.log_level.value)
+        )
+    else:
+        logging.basicConfig(level=logging.WARNING)
+
     # Set up OpenTelemetry for the worker process
     if docling_serve_settings.otel_enable_traces:
         setup_rq_worker_instrumentation()

docling_serve/settings.py

@@ -3,7 +3,7 @@ import sys
 from pathlib import Path
 from typing import Optional, Union
 
-from pydantic import AnyUrl, model_validator
+from pydantic import AnyUrl, field_validator, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from typing_extensions import Self
 
@@ -25,6 +25,12 @@ class UvicornSettings(BaseSettings):
     workers: Union[int, None] = None
 
 
+class LogLevel(str, enum.Enum):
+    WARNING = "WARNING"
+    INFO = "INFO"
+    DEBUG = "DEBUG"
+
+
 class AsyncEngine(str, enum.Enum):
     LOCAL = "local"
     KFP = "kfp"
@@ -41,6 +47,7 @@ class DoclingServeSettings(BaseSettings):
 
     enable_ui: bool = False
     api_host: str = "localhost"
+    log_level: Optional[LogLevel] = None
     artifacts_path: Optional[Path] = None
     static_path: Optional[Path] = None
     scratch_path: Optional[Path] = None
@@ -98,6 +105,16 @@ class DoclingServeSettings(BaseSettings):
     otel_enable_otlp_metrics: bool = False
     otel_service_name: str = "docling-serve"
 
+    @field_validator("log_level", mode="before")
+    @classmethod
+    def validate_log_level(cls, v: Optional[str]) -> Optional[str]:
+        """Validate and normalize log level to uppercase for case-insensitive support."""
+        if v is None:
+            return v
+        if isinstance(v, str):
+            return v.upper()
+        return v
+
     @model_validator(mode="after")
     def engine_settings(self) -> Self:
         # Validate KFP engine settings

docs/configuration.md

@@ -35,6 +35,7 @@ THe following table describes the options to configure the Docling Serve app.
 
 | CLI option | ENV | Default | Description |
 | -----------|-----|---------|-------------|
+| `-v, --verbose` | `DOCLING_SERVE_LOG_LEVEL` | `WARNING` | Set the verbosity level. CLI: `-v` for INFO, `-vv` for DEBUG. ENV: `WARNING`, `INFO`, or `DEBUG` (case-insensitive). CLI flag takes precedence over ENV. |
 | `--artifacts-path` | `DOCLING_SERVE_ARTIFACTS_PATH` | unset | If set to a valid directory, the model weights will be loaded from this path |
 |  | `DOCLING_SERVE_STATIC_PATH` | unset | If set to a valid directory, the static assets for the docs and UI will be loaded from this path |
 |  | `DOCLING_SERVE_SCRATCH_PATH` |  | If set, this directory will be used as scratch workspace, e.g. storing the results before they get requested. If unset, a temporary created is created for this purpose. |