haiway 0.19.5__py3-none-any.whl → 0.20.0__py3-none-any.whl

haiway/helpers/timeouted.py

@@ -14,23 +14,38 @@ def timeout[**Args, Result](
     [Callable[Args, Coroutine[Any, Any, Result]]],
     Callable[Args, Coroutine[Any, Any, Result]],
 ]:
-    """\
-    Timeout wrapper for a function call. \
-    When the timeout time will pass before function returns function execution will be \
-    cancelled and TimeoutError exception will raise. Make sure that wrapped \
-    function handles cancellation properly.
-    This wrapper is not thread safe.
+    """
+    Add a timeout to an asynchronous function.
+
+    This decorator enforces a maximum execution time for the decorated function.
+    If the function does not complete within the specified timeout period, it
+    will be cancelled and a TimeoutError will be raised.
 
     Parameters
     ----------
     timeout: float
-        timeout time in seconds
+        Maximum execution time in seconds allowed for the function
 
     Returns
     -------
-    Callable[[Callable[_Args, _Result]], Callable[_Args, _Result]] | Callable[_Args, _Result]
-        function wrapper adding timeout
-    """
+    Callable[[Callable[Args, Coroutine[Any, Any, Result]]], Callable[Args, Coroutine[Any, Any, Result]]]
+        A decorator that can be applied to an async function to add timeout behavior
+
+    Notes
+    -----
+    - Works only with asynchronous functions.
+    - The wrapped function will be properly cancelled when the timeout occurs.
+    - Not thread-safe, should only be used within a single event loop.
+    - The original function should handle cancellation properly to ensure
+      resources are released when timeout occurs.
+
+    Examples
+    --------
+    >>> @timeout(5.0)
+    ... async def fetch_data(url):
+    ...     # Will raise TimeoutError if it takes more than 5 seconds
+    ...     return await http_client.get(url)
+    """  # noqa: E501
 
     def _wrap(
         function: Callable[Args, Coroutine[Any, Any, Result]],

haiway/helpers/tracing.py

@@ -33,6 +33,37 @@ def traced[**Args, Result](
     level: ObservabilityLevel = ObservabilityLevel.DEBUG,
     label: str | None = None,
 ) -> Callable[[Callable[Args, Result]], Callable[Args, Result]] | Callable[Args, Result]:
+    """
+    Decorator that adds tracing to functions, recording inputs, outputs, and exceptions.
+
+    Automatically records function arguments, return values, and any exceptions
+    within the current observability context. The recorded data can be used for
+    debugging, performance analysis, and understanding program execution flow.
+
+    In non-debug builds (when __debug__ is False), this decorator has no effect
+    and returns the original function to avoid performance impact in production.
+
+    Parameters
+    ----------
+    function: Callable[Args, Result] | None
+        The function to be traced
+    level: ObservabilityLevel
+        The observability level at which to record trace information (default: DEBUG)
+    label: str | None
+        Custom label for the trace; defaults to the function name if not provided
+
+    Returns
+    -------
+    Callable
+        A decorated function that performs the same operation as the original
+        but with added tracing
+
+    Notes
+    -----
+    Works with both synchronous and asynchronous functions. For asynchronous
+    functions, properly awaits the result before recording it.
+    """
+
     def wrap(
         wrapped: Callable[Args, Result],
     ) -> Callable[Args, Result]:

haiway/opentelemetry/observability.py

@@ -1,6 +1,7 @@
 import os
 from collections.abc import Mapping
 from typing import Any, ClassVar, Self, cast, final
+from uuid import UUID
 
 from opentelemetry import metrics, trace
 from opentelemetry._logs import get_logger, set_logger_provider
@@ -37,6 +38,14 @@ __all__ = ("OpenTelemetry",)
 
 
 class ScopeStore:
+    """
+    Internal class for storing and managing OpenTelemetry scope data.
+
+    This class tracks scope state including its span, meter, logger, and context.
+    It manages the lifecycle of OpenTelemetry resources for a specific scope,
+    including recording logs, metrics, events, and maintaining the context hierarchy.
+    """
+
     __slots__ = (
         "_completed",
         "_counters",
@@ -59,6 +68,22 @@ class ScopeStore:
         meter: Meter,
         logger: Logger,
     ) -> None:
+        """
+        Initialize a new scope store with OpenTelemetry resources.
+
+        Parameters
+        ----------
+        identifier : ScopeIdentifier
+            The identifier for this scope
+        context : Context
+            The OpenTelemetry context for this scope
+        span : Span
+            The OpenTelemetry span for this scope
+        meter : Meter
+            The OpenTelemetry meter for recording metrics
+        logger : Logger
+            The OpenTelemetry logger for recording logs
+        """
         self.identifier: ScopeIdentifier = identifier
         self.nested: list[ScopeStore] = []
         self._counters: dict[str, Counter] = {}
@@ -75,17 +100,59 @@ class ScopeStore:
 
     @property
     def exited(self) -> bool:
+        """
+        Check if this scope has been marked as exited.
+
+        Returns
+        -------
+        bool
+            True if the scope has been exited, False otherwise
+        """
         return self._exited
 
     def exit(self) -> None:
+        """
+        Mark this scope as exited.
+
+        Raises
+        ------
+        AssertionError
+            If the scope has already been exited
+        """
         assert not self._exited  # nosec: B101
         self._exited = True
 
     @property
     def completed(self) -> bool:
+        """
+        Check if this scope and all its nested scopes are completed.
+
+        A scope is considered completed when it has been marked as completed
+        and all of its nested scopes are also completed.
+
+        Returns
+        -------
+        bool
+            True if the scope and all nested scopes are completed
+        """
         return self._completed and all(nested.completed for nested in self.nested)
 
     def try_complete(self) -> bool:
+        """
+        Try to complete this scope if all conditions are met.
+
+        A scope can be completed if:
+        - It has been exited
+        - It has not already been completed
+        - All nested scopes are completed
+
+        When completed, the span is ended and the context token is detached.
+
+        Returns
+        -------
+        bool
+            True if the scope was successfully completed, False otherwise
+        """
         if not self._exited:
             return False  # not elegible for completion yet
 
@@ -107,6 +174,19 @@ class ScopeStore:
         /,
         level: ObservabilityLevel,
     ) -> None:
+        """
+        Record a log message with the specified level.
+
+        Creates a LogRecord with the current span context and scope identifiers,
+        and emits it through the OpenTelemetry logger.
+
+        Parameters
+        ----------
+        message : str
+            The log message to record
+        level : ObservabilityLevel
+            The severity level of the log
+        """
         span_context: SpanContext = self.span.get_span_context()
         self.logger.emit(
             LogRecord(
@@ -116,11 +196,6 @@ class ScopeStore:
                 body=message,
                 severity_text=level.name,
                 severity_number=SEVERITY_MAPPING[level],
-                attributes={
-                    "context.trace_id": self.identifier.trace_id,
-                    "context.scope_id": self.identifier.scope_id,
-                    "context.parent_id": self.identifier.parent_id,
-                },
             )
         )
 
@@ -129,6 +204,14 @@ class ScopeStore:
         exception: BaseException,
         /,
     ) -> None:
+        """
+        Record an exception in the current span.
+
+        Parameters
+        ----------
+        exception : BaseException
+            The exception to record
+        """
         self.span.record_exception(exception)
 
     def record_event(
@@ -138,6 +221,16 @@ class ScopeStore:
         *,
         attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
+        """
+        Record an event in the current span.
+
+        Parameters
+        ----------
+        event : str
+            The name of the event to record
+        attributes : Mapping[str, ObservabilityAttribute]
+            Attributes to attach to the event
+        """
         self.span.add_event(
             event,
             attributes={
@@ -156,6 +249,23 @@ class ScopeStore:
         unit: str | None,
         attributes: Mapping[str, ObservabilityAttribute],
     ) -> None:
+        """
+        Record a metric with the given name, value, and attributes.
+
+        Creates a counter if one does not already exist for the metric name,
+        and adds the value to it with the provided attributes.
+
+        Parameters
+        ----------
+        name : str
+            The name of the metric to record
+        value : float | int
+            The value to add to the metric
+        unit : str | None
+            The unit of the metric (if any)
+        attributes : Mapping[str, ObservabilityAttribute]
+            Attributes to attach to the metric
+        """
         if name not in self._counters:
             self._counters[name] = self.meter.create_counter(
                 name=name,
@@ -165,16 +275,9 @@ class ScopeStore:
         self._counters[name].add(
             value,
             attributes={
-                **{
-                    "context.trace_id": self.identifier.trace_id,
-                    "context.scope_id": self.identifier.scope_id,
-                    "context.parent_id": self.identifier.parent_id,
-                },
-                **{
-                    key: cast(Any, value)
-                    for key, value in attributes.items()
-                    if value is not None and value is not MISSING
-                },
+                key: cast(Any, value)
+                for key, value in attributes.items()
+                if value is not None and value is not MISSING
             },
         )
 
@@ -183,6 +286,16 @@ class ScopeStore:
         attributes: Mapping[str, ObservabilityAttribute],
         /,
     ) -> None:
+        """
+        Record attributes in the current span.
+
+        Sets each attribute on the span, skipping None and MISSING values.
+
+        Parameters
+        ----------
+        attributes : Mapping[str, ObservabilityAttribute]
+            Attributes to set on the span
+        """
         for name, value in attributes.items():
             if value is None or value is MISSING:
                 continue
@@ -195,6 +308,17 @@ class ScopeStore:
 
 @final
 class OpenTelemetry:
+    """
+    Integration with OpenTelemetry for distributed tracing, metrics, and logging.
+
+    This class provides a bridge between Haiway's observability abstractions and
+    the OpenTelemetry SDK, enabling distributed tracing, metrics collection, and
+    structured logging with minimal configuration.
+
+    The class must be configured once at application startup using the configure()
+    class method before it can be used.
+    """
+
     service: ClassVar[str]
     environment: ClassVar[str]
 
@@ -210,6 +334,36 @@ class OpenTelemetry:
         export_interval_millis: int = 5000,
         attributes: Mapping[str, Any] | None = None,
     ) -> type[Self]:
+        """
+        Configure the OpenTelemetry integration.
+
+        This method must be called once at application startup to configure the
+        OpenTelemetry SDK with the appropriate service information, exporters,
+        and resource attributes.
+
+        Parameters
+        ----------
+        service : str
+            The name of the service
+        version : str
+            The version of the service
+        environment : str
+            The deployment environment (e.g., "production", "staging")
+        otlp_endpoint : str | None, optional
+            The OTLP endpoint URL to export telemetry data to. If None, console
+            exporters will be used instead.
+        insecure : bool, default=True
+            Whether to use insecure connections to the OTLP endpoint
+        export_interval_millis : int, default=5000
+            How often to export metrics, in milliseconds
+        attributes : Mapping[str, Any] | None, optional
+            Additional resource attributes to include with all telemetry
+
+        Returns
+        -------
+        type[Self]
+            The OpenTelemetry class, for method chaining
+        """
         cls.service = service
         cls.environment = environment
         # Create shared resource for both metrics and traces
@@ -284,12 +438,64 @@ class OpenTelemetry:
         cls,
         level: ObservabilityLevel = ObservabilityLevel.INFO,
     ) -> Observability:
+        """
+        Create an Observability implementation using OpenTelemetry.
+
+        This method creates an Observability implementation that bridges Haiway's
+        observability abstractions to OpenTelemetry, allowing transparent usage
+        of OpenTelemetry for distributed tracing, metrics, and logging.
+
+        Parameters
+        ----------
+        level : ObservabilityLevel, default=ObservabilityLevel.INFO
+            The minimum observability level to record
+
+        Returns
+        -------
+        Observability
+            An Observability implementation that uses OpenTelemetry
+
+        Notes
+        -----
+        The OpenTelemetry class must be configured using configure() before
+        calling this method.
+        """
         tracer: Tracer = trace.get_tracer(cls.service)
         meter: Meter | None = None
         root_scope: ScopeIdentifier | None = None
-        scopes: dict[str, ScopeStore] = {}
+        scopes: dict[UUID, ScopeStore] = {}
         observed_level: ObservabilityLevel = level
 
+        def trace_identifying(
+            scope: ScopeIdentifier,
+            /,
+        ) -> UUID:
+            """
+            Get the unique trace identifier for a scope.
+
+            This function retrieves the OpenTelemetry trace ID for the specified scope
+            and converts it to a UUID for compatibility with Haiway's observability system.
+
+            Parameters
+            ----------
+            scope: ScopeIdentifier
+                The scope identifier to get the trace ID for
+
+            Returns
+            -------
+            UUID
+                A UUID representation of the OpenTelemetry trace ID
+
+            Raises
+            ------
+            AssertionError
+                If called outside an initialized scope context
+            """
+            assert root_scope is not None  # nosec: B101
+            assert scope.scope_id in scopes  # nosec: B101
+
+            return UUID(int=scopes[scope.scope_id].span.get_span_context().trace_id)
+
         def log_recording(
             scope: ScopeIdentifier,
             /,
@@ -298,6 +504,25 @@ class OpenTelemetry:
             *args: Any,
             exception: BaseException | None,
         ) -> None:
+            """
+            Record a log message using OpenTelemetry logging.
+
+            Creates a log record with the appropriate severity level and attributes
+            based on the current scope context.
+
+            Parameters
+            ----------
+            scope: ScopeIdentifier
+                The scope identifier the log is associated with
+            level: ObservabilityLevel
+                The severity level for this log message
+            message: str
+                The log message text, may contain format placeholders
+            *args: Any
+                Format arguments for the message
+            exception: BaseException | None
+                Optional exception to associate with the log
+            """
             assert root_scope is not None  # nosec: B101
             assert scope.scope_id in scopes  # nosec: B101
 
@@ -319,6 +544,23 @@ class OpenTelemetry:
             event: str,
             attributes: Mapping[str, ObservabilityAttribute],
         ) -> None:
+            """
+            Record an event using OpenTelemetry spans.
+
+            Creates a span event with the specified name and attributes in the
+            current active span for the scope.
+
+            Parameters
+            ----------
+            scope: ScopeIdentifier
+                The scope identifier the event is associated with
+            level: ObservabilityLevel
+                The severity level for this event
+            event: str
+                The name of the event
+            attributes: Mapping[str, ObservabilityAttribute]
+                Key-value attributes associated with the event
+            """
             assert root_scope is not None  # nosec: B101
             assert scope.scope_id in scopes  # nosec: B101
 
@@ -340,6 +582,27 @@ class OpenTelemetry:
             unit: str | None,
             attributes: Mapping[str, ObservabilityAttribute],
         ) -> None:
+            """
+            Record a metric using OpenTelemetry metrics.
+
+            Records a numeric measurement using the appropriate OpenTelemetry
+            instrument type based on the metric name and value type.
+
+            Parameters
+            ----------
+            scope: ScopeIdentifier
+                The scope identifier the metric is associated with
+            level: ObservabilityLevel
+                The severity level for this metric
+            metric: str
+                The name of the metric
+            value: float | int
+                The numeric value of the metric
+            unit: str | None
+                Optional unit for the metric (e.g., "ms", "bytes")
+            attributes: Mapping[str, ObservabilityAttribute]
+                Key-value attributes associated with the metric
+            """
             assert root_scope is not None  # nosec: B101
             assert scope.scope_id in scopes  # nosec: B101
 
@@ -359,6 +622,21 @@ class OpenTelemetry:
             level: ObservabilityLevel,
             attributes: Mapping[str, ObservabilityAttribute],
         ) -> None:
+            """
+            Record standalone attributes using OpenTelemetry span attributes.
+
+            Records key-value attributes by adding them to the current active span
+            for the scope.
+
+            Parameters
+            ----------
+            scope: ScopeIdentifier
+                The scope identifier the attributes are associated with
+            level: ObservabilityLevel
+                The severity level for these attributes
+            attributes: Mapping[str, ObservabilityAttribute]
+                Key-value attributes to record
+            """
             if level < observed_level:
                 return
 
@@ -371,6 +649,27 @@ class OpenTelemetry:
             scope: ScopeIdentifier,
             /,
         ) -> None:
+            """
+            Handle scope entry by creating a new OpenTelemetry span.
+
+            This method is called when a new scope is entered. It creates a new
+            OpenTelemetry span for the scope and sets up the appropriate parent-child
+            relationships with existing spans.
+
+            Parameters
+            ----------
+            scope: ScopeIdentifier
+                The identifier for the scope being entered
+
+            Returns
+            -------
+            None
+
+            Notes
+            -----
+            This method initializes the scopes dictionary entry for the new scope
+            and creates meter instruments if this is the first scope entry.
+            """
             assert scope.scope_id not in scopes  # nosec: B101
 
             nonlocal root_scope
@@ -378,19 +677,18 @@ class OpenTelemetry:
 
             scope_store: ScopeStore
             if root_scope is None:
-                meter = metrics.get_meter(scope.trace_id)
-                context: Context = get_current()
+                meter = metrics.get_meter(scope.label)
+                context: Context = Context(
+                    **get_current(),
+                    # trace_id=scope.trace_id,
+                    # span_id=scope.scope_id,
+                )
                 scope_store = ScopeStore(
                     scope,
                     context=context,
                     span=tracer.start_span(
                         name=scope.label,
                         context=context,
-                        attributes={
-                            "context.trace_id": scope.trace_id,
-                            "context.scope_id": scope.scope_id,
-                            "context.parent_id": scope.parent_id,
-                        },
                     ),
                     meter=meter,
                     logger=get_logger(scope.label),
@@ -405,11 +703,6 @@ class OpenTelemetry:
                     span=tracer.start_span(
                         name=scope.label,
                         context=scopes[scope.parent_id].context,
-                        attributes={
-                            "context.trace_id": scope.trace_id,
-                            "context.scope_id": scope.scope_id,
-                            "context.parent_id": scope.parent_id,
-                        },
                     ),
                     meter=meter,
                     logger=get_logger(scope.label),
@@ -424,6 +717,28 @@ class OpenTelemetry:
             *,
             exception: BaseException | None,
         ) -> None:
+            """
+            Handle scope exit by completing the OpenTelemetry span.
+
+            This method is called when a scope is exited. It marks the scope as exited,
+            attempts to complete it, and ends the associated OpenTelemetry span.
+
+            Parameters
+            ----------
+            scope: ScopeIdentifier
+                The identifier for the scope being exited
+            exception: BaseException | None
+                Optional exception that caused the scope to exit
+
+            Returns
+            -------
+            None
+
+            Notes
+            -----
+            This method ensures proper cleanup of spans, including recording any
+            exception that occurred during the scope's execution.
+            """
             nonlocal root_scope
             nonlocal scopes
             nonlocal meter
@@ -442,7 +757,7 @@ class OpenTelemetry:
 
             # try complete parent scopes
             if scope != root_scope:
-                parent_id: str = scope.parent_id
+                parent_id: UUID = scope.parent_id
                 while scopes[parent_id].try_complete():
                     if scopes[parent_id].identifier == root_scope:
                         break
@@ -457,6 +772,7 @@ class OpenTelemetry:
                 scopes = {}
 
         return Observability(
+            trace_identifying=trace_identifying,
             log_recording=log_recording,
             event_recording=event_recording,
             metric_recording=metric_recording,
@@ -472,3 +788,4 @@ SEVERITY_MAPPING = {
     ObservabilityLevel.WARNING: SeverityNumber.WARN,
     ObservabilityLevel.ERROR: SeverityNumber.ERROR,
 }
+"""Mapping from Haiway ObservabilityLevel to OpenTelemetry SeverityNumber."""