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).

   The module supports both legacy dict-based configs and new template-based
   configurations. Requester logs are automatically captured by OTLP when
   enabled (handled by the Requester class itself).



Attributes
----------

.. autoapisummary::

   client.logging._structlog_configured_lock
   client.logging._structlog_configured_by_jobmon
   client.logging._DEFAULT_LOG_FORMAT
   client.logging.default_config


Functions
---------

.. autoapisummary::

   client.logging.ensure_structlog_configured
   client.logging.configure_client_logging
   client.logging._remove_non_jobmon_handlers
   client.logging._configure_client_logging_for_direct_rendering
   client.logging._ensure_jobmon_otlp_handlers


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

.. py:data:: _structlog_configured_lock

.. py:data:: _structlog_configured_by_jobmon
   :value: False


.. py:data:: _DEFAULT_LOG_FORMAT
   :value: '%(asctime)s [%(name)-12s] %(module)s %(levelname)-8s: %(message)s'


.. 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 template and user override support.

   This is the primary interface for configuring client logging. It supports:
   1. Default template-based configuration
   2. User file overrides via logging.client_logconfig_file
   3. User section overrides via logging.client.*
   4. Environment variable overrides

   Configuration precedence:
   1. Custom file (logging.client_logconfig_file)
   2. Section overrides (logging.client.formatters/handlers/loggers)
   3. Default template (logconfig_client.yaml)
   4. Basic fallback configuration

   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.


.. py:function:: _remove_non_jobmon_handlers(logconfig: Dict) -> List[str]

   Keep only Jobmon OTLP handlers when host renders output directly.


.. py:function:: _configure_client_logging_for_direct_rendering(*, default_template_path: str, logger_factory: Any, wrapper_class: Any) -> None

   Configure logging for direct-rendering hosts while preserving telemetry.


.. py:function:: _ensure_jobmon_otlp_handlers(logconfig_data: Dict[str, Any], jobmon_logger_names: Optional[Iterable[str]] = None) -> List[str]

   Attach OTLP handlers if jobmon loggers ended up without handlers.