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

.. py:module:: corvix.observability.middleware

.. autoapi-nested-parse::

   ASGI middleware recording per-request metrics, request IDs, and trace spans.

   Sits outermost in the middleware stack so it observes every request (including
   auth failures), tags each one with a ``request_id`` bound into the logging
   context and echoed back in the ``X-Request-ID`` response header, and records
   request counts and latency by method, endpoint, and status.



Attributes
----------

.. autoapisummary::

   corvix.observability.middleware._REQUEST_ID_HEADER
   corvix.observability.middleware._UNKNOWN_ENDPOINT


Classes
-------

.. autoapisummary::

   corvix.observability.middleware.ObservabilityMiddleware


Functions
---------

.. autoapisummary::

   corvix.observability.middleware._endpoint_label
   corvix.observability.middleware._request_id


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

.. py:data:: _REQUEST_ID_HEADER
   :value: b'x-request-id'


.. py:data:: _UNKNOWN_ENDPOINT
   :value: 'unknown'


.. py:function:: _endpoint_label(scope: litestar.types.asgi_types.Scope) -> str

   Return a low-cardinality endpoint label from the matched route.

   Uses the registered path *template* (e.g. ``/api/v1/notifications/{account_id}/...``)
   rather than the concrete path so per-ID paths do not explode label cardinality.


.. py:function:: _request_id(scope: litestar.types.asgi_types.Scope) -> str

.. py:class:: ObservabilityMiddleware

   Bases: :py:obj:`litestar.middleware.base.ASGIMiddleware`


   Record request metrics, bind a request ID, and open a trace span.


   .. py:attribute:: scopes


   .. py:method:: handle(scope: litestar.types.asgi_types.Scope, receive: litestar.types.asgi_types.Receive, send: litestar.types.asgi_types.Send, next_app: litestar.types.asgi_types.ASGIApp) -> None
      :async:


      Wrap the downstream app with metrics, logging context, and a span.