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

.. py:module:: corvix.observability

.. autoapi-nested-parse::

   Observability for Corvix: structured logging, Prometheus metrics, OTel tracing.

   * Structured JSON logging via :func:`configure_logging` (always available).
   * Prometheus metrics via the :mod:`corvix.observability.metrics` module and the
     ``/metrics`` web endpoint.
   * Optional OpenTelemetry tracing via :func:`setup_tracing` and :func:`span`
     (requires the ``otel`` extra and ``CORVIX_OTEL_ENABLED``).



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/corvix/observability/logging/index
   /autoapi/corvix/observability/metrics/index
   /autoapi/corvix/observability/middleware/index
   /autoapi/corvix/observability/tracing/index


Functions
---------

.. autoapisummary::

   corvix.observability.bind_log_context
   corvix.observability.configure_logging
   corvix.observability.reset_log_context
   corvix.observability.is_enabled
   corvix.observability.setup_tracing
   corvix.observability.span


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

.. 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:: 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.


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

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


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

   Return whether tracing has been successfully configured.


.. py:function:: setup_tracing(service_name: str | None = None) -> bool

   Configure the global tracer provider when tracing is requested.

   Returns ``True`` when tracing is active afterwards. A no-op (returning
   ``False``) when ``CORVIX_OTEL_ENABLED`` is not truthy or the ``otel`` extra
   is not installed. Safe to call multiple times.


.. py:function:: span(name: str, attributes: collections.abc.Mapping[str, Any] | None = None) -> collections.abc.Iterator[Any]

   Start a span as the current context, or no-op when tracing is disabled.

   Yields the active span (or ``None`` when disabled). Exceptions raised in the
   block are recorded on the span and re-raised.