Process log forwarding
======================

Logs emitted inside ``ProcessPoolExecutor`` workers are created in child
processes. They do not automatically flow through the parent application's
logger handlers.

``leasepool`` provides optional process log forwarding for the process backend.
It installs a queue handler in each worker and a queue listener in the parent
process.

Explicit configuration
----------------------

Use ``ProcessLoggingConfig`` when you want one object that documents the logging
bridge configuration:

.. literalinclude:: ../../../examples/13_process_log_forwarding.py
   :language: python
   :caption: examples/13_process_log_forwarding.py

Convenience configuration
-------------------------

For shorter setup, pass the convenience arguments directly to the manager:

.. code-block:: python

   import logging

   from leasepool import LeasedExecutorManager


   manager = LeasedExecutorManager(
       backend="process",
       max_pools=1,
       min_pools=1,
       workers_per_pool=2,
       forward_process_logs=True,
       process_log_level="INFO",
       process_log_target_logger=logging.getLogger("myapp.process-workers"),
   )

Do not pass both ``process_logging`` and the convenience arguments in the same
manager.

Configuration fields
--------------------

``enabled``
   Enable child-process log forwarding.

``level``
   Minimum level configured on the child-process root logger. Accepts an integer
   logging level or a standard level name such as ``"INFO"``.

``target_logger``
   Parent-process logger that receives worker log records. If omitted, the
   manager's logger is used.

``clear_child_handlers``
   Remove existing child-process root handlers before installing the queue
   handler. Defaults to ``True`` to avoid duplicate records after fork.

Composing worker initializers
-----------------------------

If you pass ``initializer`` and ``initargs`` to the process executor, leasepool
preserves them when log forwarding is enabled:

.. code-block:: python

   manager = LeasedExecutorManager(
       backend="process",
       max_pools=1,
       forward_process_logs=True,
       initializer=configure_worker,
       initargs=("worker-config",),
   )

The leasepool logging initializer runs first, then your initializer runs.

When to enable it
-----------------

Enable process log forwarding when worker logs are important for debugging,
monitoring, or audit trails.

Leave it disabled when workers do not log or when you have your own
process-aware logging setup.
