core.config.structlog_config

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

enable_structlog_otlp_capture(→ None)

Enable thread-local capture for OTLP handlers.

disable_structlog_otlp_capture(→ None)

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

structlog_otlp_capture_enabled(→ Iterator[None])

Context manager to enable OTLP capture temporarily.

configure_structlog(→ None)

Configure structlog for jobmon components.

create_telemetry_isolation_processor(→ Callable[[Any, ...)

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

configure_structlog_with_otlp(→ None)

Configure structlog with OTLP trace integration if enabled.

prepend_jobmon_processors_to_existing_config(→ None)

Prepend Jobmon processors to an existing structlog configuration.

is_structlog_configured(→ bool)

Check if structlog has been configured.

Module Contents

core.config.structlog_config.enable_structlog_otlp_capture() → None

Enable thread-local capture for OTLP handlers.

core.config.structlog_config.disable_structlog_otlp_capture() → None

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

core.config.structlog_config.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.

core.config.structlog_config.configure_structlog(component_name: str | None = None, *, extra_processors: Iterable[Callable] | None = 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)

Parameters:

  • component_name – Component name to add to all logs (e.g., “distributor”)

  • 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")
core.config.structlog_config.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.

Parameters:

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.

core.config.structlog_config.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.

Parameters:

component_name – Component name (e.g., “distributor”, “worker”)

Example

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

>>> # In worker CLI
>>> configure_structlog_with_otlp(component_name="worker")
core.config.structlog_config.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

core.config.structlog_config.is_structlog_configured() → bool

Check if structlog has been configured.

Returns:

True if structlog is configured, False otherwise

Example

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