Heuristic:Deepset ai Haystack Logging Auto Detection
| Knowledge Sources | |
|---|---|
| Domains | Logging, Configuration |
| Last Updated | 2026-02-11 20:00 GMT |
Overview
Haystack auto-detects the logging output format (console vs JSON) based on TTY status and Jupyter environment; override with HAYSTACK_LOGGING_USE_JSON or HAYSTACK_LOGGING_IGNORE_STRUCTLOG environment variables.
Description
When structlog is installed, Haystack's configure_logging() function automatically selects between human-readable console output and machine-parseable JSON output. The detection logic checks sys.stderr.isatty() and whether the code is running inside a Jupyter notebook. Interactive environments get colored console output; non-interactive environments (containers, CI) get JSON. Two environment variables provide explicit overrides.
Usage
Apply this heuristic when deploying Haystack in containers or CI where logs appear garbled, when debugging in Jupyter notebooks where structured JSON is unreadable, or when integrating with log aggregation systems (ELK, Datadog) that expect JSON.
The Insight (Rule of Thumb)
- Action: Set
HAYSTACK_LOGGING_USE_JSON=trueto force JSON output in any environment. - Action: Set
HAYSTACK_LOGGING_IGNORE_STRUCTLOG=trueto disable structlog integration entirely and fall back to standard Python logging. - Value: Automatic format selection works correctly for most environments (TTY = console, non-TTY = JSON).
- Trade-off: Auto-detection can fail in edge cases (e.g., remote terminals that report as non-TTY); use explicit env vars in those cases.
Reasoning
The detection logic in haystack/logging.py:331-335:
use_json_env_var = os.getenv(HAYSTACK_LOGGING_USE_JSON_ENV_VAR)
# ...
sys.stderr.isatty() or hasattr(builtins, "__IPYTHON__") or haystack.utils.jupyter.is_in_jupyter()
The function checks three conditions to determine interactivity: stderr being a TTY, IPython being loaded (Jupyter kernel), or the Jupyter check utility returning True. If none are met, JSON output is assumed for production environments. The HAYSTACK_LOGGING_IGNORE_STRUCTLOG env var at line 322 provides a full bypass.