core.otlp
=========

.. py:module:: core.otlp

.. autoapi-nested-parse::

   Elegant OTLP integration for jobmon that prevents global log pollution.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/core/otlp/formatters/index
   /autoapi/core/otlp/handlers/index
   /autoapi/core/otlp/manager/index
   /autoapi/core/otlp/resources/index
   /autoapi/core/otlp/utils/index


Attributes
----------

.. autoapisummary::

   core.otlp.OTLP_AVAILABLE
   core.otlp.OpenTelemetryLogFormatter


Classes
-------

.. autoapisummary::

   core.otlp.JobmonOTLPFormatter
   core.otlp.JobmonOTLPLoggingHandler
   core.otlp.JobmonOTLPStructlogHandler


Functions
---------

.. autoapisummary::

   core.otlp.add_span_details_processor
   core.otlp.get_current_span_details


Package Contents
----------------

.. py:data:: OTLP_AVAILABLE
   :value: True


.. py:class:: JobmonOTLPFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

   Bases: :py:obj:`logging.Formatter`


   Formatter that adds OpenTelemetry span details to jobmon logs.

   Note: For handlers using _JobmonOTLPLoggingHandler, this formatter is not
   used for OTLP output (handler creates OTLPLogRecord directly). It only
   affects console/file output.


   .. py:method:: format(record: logging.LogRecord) -> str

      Format log record with OpenTelemetry span details.



.. py:class:: JobmonOTLPLoggingHandler(level: int = logging.NOTSET, exporter: Optional[Union[Any, Dict]] = None, logger_provider: Optional[Any] = None)

   Bases: :py:obj:`logging.Handler`


   Universal OTLP logging handler with lazy initialization and attribute extraction.

   This handler extracts attributes from structlog's thread-local event_dict and
   supports flexible configuration patterns:

   1. Inline dict configuration (server pattern):
       handlers:
         otlp_logs:
           class: jobmon.core.otlp.JobmonOTLPLoggingHandler
           level: INFO
           exporter:
             module: opentelemetry.exporter.otlp.proto.grpc._log_exporter
             class: OTLPLogExporter
             endpoint: otelcol.dev.aks.scicomp.ihme.washington.edu:443
             options: [["grpc.max_send_message_length", 16777216]]
             max_export_batch_size: 8

   2. Pre-configured exporter instance:
       handler = JobmonOTLPLoggingHandler(exporter=my_exporter)

   3. Direct use with logger_provider (for testing):
       handler = JobmonOTLPLoggingHandler(logger_provider=my_provider)


   .. py:attribute:: _SEVERITY_MAP
      :value: None



   .. py:method:: _get_severity_map() -> Dict[str, Any]
      :classmethod:


      Get severity map with lazy import.



   .. py:attribute:: _exporter_config
      :value: None



   .. py:attribute:: _logger_provider
      :value: None



   .. py:attribute:: _logger
      :type:  Optional[Any]
      :value: None



   .. py:attribute:: _initialized
      :value: False



   .. py:attribute:: _capture_registered
      :value: False



   .. py:method:: _ensure_initialized() -> bool

      Ensure logger provider is initialized. Returns True if ready.



   .. py:method:: close() -> None

      Tidy up any resources used by the handler.

      This version removes the handler from an internal map of handlers,
      _handlers, which is used for handler lookup by name. Subclasses
      should ensure that this gets called from overridden close()
      methods.



   .. py:method:: _extract_attributes(event_dict: Dict[str, Any]) -> Dict[str, Any]

      Extract OTLP attributes from event_dict.

      Strips the 'telemetry_' prefix from attribute names for cleaner OTLP exports
      while maintaining internal namespacing.



   .. py:method:: _parse_trace_context(event_dict: Optional[Dict[str, Any]]) -> tuple[int, int]

      Parse trace and span IDs from event_dict or current span.



   .. py:method:: emit(record: logging.LogRecord) -> None

      Emit log record to OTLP with extracted attributes.



.. py:class:: JobmonOTLPStructlogHandler(level: int = logging.NOTSET, exporter: Optional[Union[Any, Dict]] = None, logger_provider: Optional[Any] = None)

   Bases: :py:obj:`JobmonOTLPLoggingHandler`


   OTLP logging handler for structlog.

   Identical to JobmonOTLPLoggingHandler - uses the same custom handler that
   extracts attributes from thread-local event_dict. This class exists for
   clarity in configuration (to indicate structlog support) but functionally
   is the same as the parent class.


.. py:function:: add_span_details_processor(logger: Any, method_name: str, event_dict: Dict[str, Any]) -> Dict[str, Any]

   Structlog processor to add OpenTelemetry span details to log entries.

   :param logger: The logger instance (not used, but required by Structlog processor signature).
   :param method_name: The logging method name (e.g., "info", "debug").
   :param event_dict: The event dictionary representing the log entry.

   :returns: The modified event dictionary with OpenTelemetry span details added.


.. py:function:: get_current_span_details() -> Tuple[Optional[str], Optional[str], Optional[str]]

   Get details of the current OpenTelemetry span.

   :returns: Tuple of (span_id, trace_id, parent_span_id) as hex strings, or (None, None, None)


.. py:data:: OpenTelemetryLogFormatter