client.logging
==============

.. py:module:: client.logging

.. autoapi-nested-parse::

   Logging configuration for jobmon client applications.

   This module provides the standard logging configuration used by
   workflow.run(configure_logging=True).

   Configuration is generated programmatically with support for user overrides
   via JobmonConfig. Requester logs are automatically captured by OTLP when
   enabled (handled by the Requester class itself).



Attributes
----------

.. autoapisummary::

   client.logging.default_config


Functions
---------

.. autoapisummary::

   client.logging.ensure_structlog_configured
   client.logging.configure_client_logging


Module Contents
---------------

.. py:data:: default_config
   :type:  Dict

.. py:function:: ensure_structlog_configured() -> None

   Ensure structlog is configured for Jobmon, using lazy initialization.

   This function is called at the start of key Jobmon operations (workflow.run(),
   workflow.bind(), etc.) to ensure structlog is configured. It uses a lock to
   ensure thread-safe initialization.

   Behavior:
   - If host has already configured structlog: prepend Jobmon processors
   - If structlog is unconfigured: configure it with Jobmon defaults
   - If already called: no-op (idempotent)

   This lazy approach ensures host applications always have the opportunity to
   configure structlog first, eliminating import-order dependencies.


.. py:function:: configure_client_logging() -> None

   Configure client logging with programmatic generation and user override support.

   This is the primary interface for configuring client logging. It supports:

   1. User file overrides via ``logging.client_logconfig_file``
   2. User section overrides via ``logging.client.*``
   3. Environment variable overrides
   4. Programmatic base configuration

   Configuration precedence:

   1. Custom file (``logging.client_logconfig_file``) - complete replacement
   2. Section overrides (``logging.client.*``) - merged with base
   3. Programmatic base: ``generate_component_logconfig("client")``

   Adapts to host application logging architecture:

   - If host uses direct rendering (like FHS): sets up minimal stdlib handlers
     that pass through formatted output without double-processing
   - If host uses stdlib integration: sets up full Jobmon logging configuration

   Note: Requester OTLP is handled separately by the Requester class.