core.config.structlog_config
============================

.. py:module:: core.config.structlog_config

.. autoapi-nested-parse::

   Shared structlog configuration for all jobmon components.

   This module provides structlog configuration that enables:

   1. Context variable merging (required for ``@bind_context`` decorator)
   2. Basic stdlib metadata decoration (logger name, level) while deferring
      rendering/formatting to the host application
   3. Optional Jobmon telemetry isolation and OTLP capture
   4. Optional component identification in logs



Functions
---------

.. autoapisummary::

   core.config.structlog_config.enable_structlog_otlp_capture
   core.config.structlog_config.disable_structlog_otlp_capture
   core.config.structlog_config.structlog_otlp_capture_enabled
   core.config.structlog_config.configure_structlog
   core.config.structlog_config.create_telemetry_isolation_processor
   core.config.structlog_config.configure_structlog_with_otlp
   core.config.structlog_config.prepend_jobmon_processors_to_existing_config
   core.config.structlog_config.is_structlog_configured


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

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

   Enable thread-local capture for OTLP handlers.


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

   Disable OTLP capture (used for tests or when handlers are removed).


.. py:function:: structlog_otlp_capture_enabled() -> Iterator[None]

   Context manager to enable OTLP capture temporarily.

   Ensures the reference count is decremented even if an exception is raised.
   Particularly useful in tests that need to toggle capture around assertions.


.. py:function:: configure_structlog(component_name: Optional[str] = None, *, extra_processors: Optional[Iterable[Callable]] = None) -> None

   Configure structlog for jobmon components.

   This function sets up structlog with processors that:

   1. Merge context variables (from bind_contextvars and ``@bind_context`` decorator)
   2. Add logger metadata (logger name, log level)
   3. Optionally add a component field to the event_dict
   4. Isolate Jobmon telemetry metadata to jobmon.* loggers
   5. Capture the raw event_dict for OTLP handlers
   6. Optionally include extra processors supplied by the caller

   IMPORTANT: This must be called before using the ``@bind_context`` decorator
   or any ``structlog.contextvars.bind_contextvars()`` calls.

   PROCESSOR CHAIN ORDER (after configuration):

   1. merge_contextvars (Jobmon context)
   2. component processor (optional, when component_name is provided)
   3. filter_by_level (stdlib)
   4. add_logger_name (stdlib)
   5. add_log_level (stdlib)
   6. telemetry isolation processor
   7. ``_store_event_dict_for_otlp`` (Jobmon OTLP capture)
   8. Extra processors supplied via ``extra_processors`` (if any)
   9. ProcessorFormatter.wrap_for_formatter (stdlib - keeps stdlib handlers working)

   :param component_name: Component name to add to all logs (e.g., "distributor")
   :param extra_processors: Additional structlog processors to append after Jobmon's
                            defaults (e.g., custom formatting or telemetry processors)

   Example::

       # Basic usage
       configure_structlog(component_name="distributor")


.. py:function:: create_telemetry_isolation_processor(telemetry_prefixes: List[str]) -> Callable[[Any, str, Dict[str, Any]], Dict[str, Any]]

   Create a processor that isolates telemetry metadata to specific logger prefixes.

   :param telemetry_prefixes: List of logger name prefixes that should receive telemetry
                              metadata (e.g., ["jobmon.", "myapp.telemetry"]).

   :returns: A structlog processor function that isolates telemetry metadata.


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

   Configure structlog with OTLP trace integration if enabled.

   Checks JobmonConfig for telemetry.tracing settings and configures
   structlog with OpenTelemetry trace processors if enabled.

   This is the recommended function to call from component CLIs as it
   automatically handles OTLP configuration based on settings.

   :param component_name: Component name (e.g., "distributor", "worker")

   .. rubric:: Example

   >>> # In distributor CLI
   >>> configure_structlog_with_otlp(component_name="distributor")

   >>> # In worker CLI
   >>> configure_structlog_with_otlp(component_name="worker")


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

   Prepend Jobmon processors to an existing structlog configuration.

   This is called when Jobmon is used as a library and the host application
   has already configured structlog. It intelligently prepends Jobmon's processors
   to the existing processor chain to enable telemetry context management and isolation
   while preserving the host application's final rendering.

   Adapts to the host app's logging architecture:

   - Stdlib integration adds ``merge_contextvars``, ``filter_by_level``,
     ``add_logger_name``, and telemetry isolation
   - Direct rendering (like FHS) adds ``merge_contextvars`` and telemetry isolation
   - Host processors remain untouched so final rendering is preserved


.. py:function:: is_structlog_configured() -> bool

   Check if structlog has been configured.

   :returns: True if structlog is configured, False otherwise

   .. rubric:: Example

   >>> if not is_structlog_configured():
   ...     configure_structlog(component_name="my_component")