deepset-ai--haystack/releasenotes/notes/scope-logging-configuration-4a38bf0c8ea89fc9.yaml

---
upgrade:
  - |
    ``haystack.logging.configure_logging`` now attaches its formatting handler to Haystack's own logger namespaces
    (``haystack``, ``haystack_integrations`` and ``haystack_experimental``) instead of the root logger. This makes
    Haystack a better-behaved library when it runs next to other services in the same process: the log records of the
    host application and other libraries are no longer reformatted or duplicated by Haystack. To restore the previous
    behavior of formatting every log record in the process, call ``configure_logging(logger_name="")``.
  - |
    Importing Haystack no longer configures ``structlog`` process-wide. The import-time setup now only installs
    Haystack's own scoped logging handler (so Haystack's logs are still formatted) and leaves the global ``structlog``
    configuration untouched, so the host application's own native ``structlog`` loggers are no longer reformatted by
    merely importing Haystack. ``structlog`` is configured only when you call
    ``configure_logging(configure_structlog=True)``.
fixes:
  - |
    ``haystack.logging.configure_logging`` no longer freezes the log level at import time. Previously the level was
    captured once when the function ran (at ``import haystack``), so a log level set later by the application was
    ignored for ``structlog``-native loggers. The effective level is now read on every log call.
  - |
    Fixed the logger in ``haystack.utils.requests_utils`` being named after the module's file path instead of
    ``haystack.utils.requests_utils``, which kept its records outside the ``haystack`` logger namespace.
  - |
    ``haystack.logging.getLogger`` is now idempotent. Previously, calling it more than once for the same logger name
    wrapped the already-wrapped logger methods again, which caused the log message to be run through ``str.format``
    once per call. As a result a field value containing ``{...}`` could be re-interpolated and pull in the value of
    another field. Each logger is now patched only once.
  - |
    The patched ``findCaller`` used to determine the source of a log entry no longer prints to stdout and no longer
    masks errors with a misleading ``NameError``, matching structlog's own ``findCaller`` implementation.
features:
  - |
    ``haystack.logging.configure_logging`` gained three parameters: ``logger_name`` to choose which logger(s) the
    formatting handler is attached to, ``propagate`` to control whether Haystack's loggers propagate their records to
    ancestor loggers, and ``configure_structlog`` to control whether the call configures the process-global
    ``structlog`` (taking over any existing configuration). Set ``propagate=False`` to let Haystack fully own the
    output of its own logs and avoid duplicate log lines when the host application also configures the root logger.