core.config.logconfig_utils
===========================

.. py:module:: core.config.logconfig_utils

.. autoapi-nested-parse::

   Utilities for loading and overriding logging configurations.

   This module provides functions to load template-based logconfigs and apply
   user-specified overrides from JobmonConfig.

   The primary configuration is generated programmatically via generate_component_logconfig(),
   with support for file-based and section-based overrides from JobmonConfig.



Attributes
----------

.. autoapisummary::

   core.config.logconfig_utils.SHARED_FORMATTERS


Functions
---------

.. autoapisummary::

   core.config.logconfig_utils.generate_component_logconfig
   core.config.logconfig_utils.merge_logconfig_sections
   core.config.logconfig_utils.load_logconfig_with_overrides
   core.config.logconfig_utils.configure_logging_with_overrides
   core.config.logconfig_utils.get_logconfig_examples
   core.config.logconfig_utils.configure_component_logging


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

.. py:data:: SHARED_FORMATTERS
   :type:  Dict[str, Any]

.. py:function:: generate_component_logconfig(component: str, log_level: str = 'INFO', console_level: str = 'INFO', otlp_level: str = 'DEBUG', disable_existing_loggers: bool = False, include_core_logger: bool = True) -> Dict[str, Any]

   Generate a logconfig dictionary for a jobmon component.

   This is the single source of truth for component logging configuration.
   All component logconfigs share the same structure, differing only in
   the logger namespace and optional settings.

   :param component: Component name ('client', 'distributor', 'worker', 'server')
   :param log_level: Log level for the component's primary logger
   :param console_level: Log level for console handler
   :param otlp_level: Log level for OTLP handler
   :param disable_existing_loggers: Whether to disable existing loggers
   :param include_core_logger: Whether to include a jobmon.core logger

   :returns: Complete logconfig dictionary ready for logging.config.dictConfig()

   .. rubric:: Example

   >>> config = generate_component_logconfig("distributor", log_level="DEBUG")
   >>> logging.config.dictConfig(config)


.. py:function:: merge_logconfig_sections(base_config: Dict[str, Any], overrides: Dict[str, Any]) -> Dict[str, Any]

   Merge logconfig section overrides into base configuration.

   This performs a deep merge, allowing users to override specific formatters,
   handlers, or loggers while preserving the rest of the base configuration.

   :param base_config: Base logconfig dictionary (from templates)
   :param overrides: Override sections from JobmonConfig

   :returns: Merged logconfig dictionary


.. py:function:: load_logconfig_with_overrides(default_template_path: str, config_section: str, config: Optional[jobmon.core.configuration.JobmonConfig] = None) -> Dict[str, Any]

   Load logconfig with support for user overrides from JobmonConfig.

   Supports two types of overrides:
   1. File-based: Custom logconfig file specified in logging.{component}_logconfig_file
   2. Section-based: Override specific sections specified in logging.{component}.*

   :param default_template_path: Path to the default template-based logconfig
   :param config_section: Config section name ('client', 'server', 'requester')
   :param config: JobmonConfig instance (creates default if None)

   :returns: Fully resolved logconfig dictionary ready for logging.config.dictConfig()


.. py:function:: configure_logging_with_overrides(default_template_path: str, config_section: str, fallback_config: Optional[Dict[str, Any]] = None, config: Optional[jobmon.core.configuration.JobmonConfig] = None) -> None

   Configure logging with template and override support.

   This is a convenience function that loads a logconfig with overrides
   and applies it using logging.config.dictConfig().

   :param default_template_path: Path to the default template-based logconfig
   :param config_section: Config section name ('client', 'server', 'requester')
   :param fallback_config: Fallback config if template loading fails
   :param config: JobmonConfig instance (creates default if None)


.. py:function:: get_logconfig_examples() -> Dict[str, Dict[str, Any]]

   Get example configurations for documentation and testing.

   :returns: Dictionary of example logconfig override configurations by component


.. py:function:: configure_component_logging(component_name: str) -> None

   Configure logging for jobmon components.

   Uses programmatic configuration as the base, with support for file-based
   and section-based overrides from JobmonConfig.

   Configuration precedence:
   1. File override: logging.{component}_logconfig_file (complete replacement)
   2. Section override: logging.{component}.* (merged with base)
   3. Programmatic base: generate_component_logconfig()

   :param component_name: Component name ('client', 'distributor', 'worker', 'server')