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

.. py:module:: corvix.observability.tracing

.. autoapi-nested-parse::

   Optional OpenTelemetry tracing for Corvix.

   Tracing is opt-in: it requires the ``otel`` extra to be installed *and*
   ``CORVIX_OTEL_ENABLED`` to be truthy. When either is missing, :func:`span` is a
   zero-overhead no-op so call sites never need to branch on availability.

   The OTLP exporter honours the standard ``OTEL_*`` environment variables (e.g.
   ``OTEL_EXPORTER_OTLP_ENDPOINT``); only ``CORVIX_OTEL_ENABLED`` and an optional
   service-name override are Corvix-specific.



Attributes
----------

.. autoapisummary::

   corvix.observability.tracing.logger
   corvix.observability.tracing._OTEL_AVAILABLE
   corvix.observability.tracing._TRACER_NAME
   corvix.observability.tracing._enabled


Functions
---------

.. autoapisummary::

   corvix.observability.tracing._truthy
   corvix.observability.tracing.is_enabled
   corvix.observability.tracing.setup_tracing
   corvix.observability.tracing.span


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

.. py:data:: logger

.. py:data:: _OTEL_AVAILABLE
   :value: True


.. py:data:: _TRACER_NAME
   :value: 'corvix'


.. py:data:: _enabled
   :value: False


.. py:function:: _truthy(value: str | None) -> bool

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