corvix.observability.logging
============================

.. py:module:: corvix.observability.logging

.. autoapi-nested-parse::

   Structured JSON logging for Corvix.

   Provides :func:`configure_logging`, which installs a single stdout handler on
   the root logger emitting one JSON object per line with a consistent schema:
   ``timestamp``, ``level``, ``logger``, ``module``, ``event`` and any extra
   fields passed via ``logger.*(..., extra={...})``.

   A :mod:`contextvars`-based context (see :func:`bind_log_context`) lets request
   scoped fields such as ``request_id`` be attached to every log line emitted while
   handling a request without threading them through every call.



Attributes
----------

.. autoapisummary::

   corvix.observability.logging._RESERVED_RECORD_KEYS
   corvix.observability.logging._log_context
   corvix.observability.logging._LOG_FORMAT_JSON
   corvix.observability.logging._LOG_FORMAT_CONSOLE
   corvix.observability.logging._handler


Classes
-------

.. autoapisummary::

   corvix.observability.logging.JsonFormatter


Functions
---------

.. autoapisummary::

   corvix.observability.logging._current_context
   corvix.observability.logging.bind_log_context
   corvix.observability.logging.reset_log_context
   corvix.observability.logging._build_handler
   corvix.observability.logging.configure_logging


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

.. py:data:: _RESERVED_RECORD_KEYS
   :type:  frozenset[str]

.. py:data:: _log_context
   :type:  contextvars.ContextVar[dict[str, object] | None]

.. py:data:: _LOG_FORMAT_JSON
   :value: 'json'


.. py:data:: _LOG_FORMAT_CONSOLE
   :value: 'console'


.. py:data:: _handler
   :type:  logging.Handler | None
   :value: None


.. py:function:: _current_context() -> dict[str, object]

.. py:function:: bind_log_context(**fields: object) -> dict[str, object] | None

   Merge *fields* into the current logging context and return the previous one.

   The returned value should be passed to :func:`reset_log_context` to restore
   the prior state (typically in a ``finally`` block).


.. py:function:: reset_log_context(previous: dict[str, object] | None) -> None

   Restore a logging context previously returned by :func:`bind_log_context`.


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

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


   Render log records as single-line JSON objects.


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

      Format the specified record as text.

      The record's attribute dictionary is used as the operand to a
      string formatting operation which yields the returned string.
      Before formatting the dictionary, a couple of preparatory steps
      are carried out. The message attribute of the record is computed
      using LogRecord.getMessage(). If the formatting string uses the
      time (as determined by a call to usesTime(), formatTime() is
      called to format the event time. If there is exception information,
      it is formatted using formatException() and appended to the message.



.. py:function:: _build_handler(log_format: str) -> logging.Handler

.. py:function:: configure_logging(level: str | None = None, log_format: str | None = None) -> None

   Install the structured logging handler on the root logger.

   ``level`` defaults to ``CORVIX_LOG_LEVEL`` (then ``INFO``) and ``log_format``
   to ``CORVIX_LOG_FORMAT`` (then ``json``; ``console`` selects a human-readable
   formatter for local development). Safe to call multiple times — the Corvix
   handler is only installed once.