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

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

haiway/state/attributes.py

@@ -34,6 +34,14 @@ __all__ = (
 
 @final
 class AttributeAnnotation:
+    """
+    Represents a type annotation for a State attribute with additional metadata.
+
+    This class encapsulates information about a type annotation, including its
+    origin type, type arguments, whether it's required, and any extra metadata.
+    It's used internally by the State system to track and validate attribute types.
+    """
+
     __slots__ = (
         "arguments",
         "extra",
@@ -49,6 +57,20 @@ class AttributeAnnotation:
         required: bool = True,
         extra: Mapping[str, Any] | None = None,
     ) -> None:
+        """
+        Initialize a new attribute annotation.
+
+        Parameters
+        ----------
+        origin : Any
+            The base type of the annotation (e.g., str, int, List)
+        arguments : Sequence[Any] | None
+            Type arguments for generic types (e.g., T in List[T])
+        required : bool
+            Whether this attribute is required (cannot be omitted)
+        extra : Mapping[str, Any] | None
+            Additional metadata about the annotation
+        """
         self.origin: Any = origin
         self.arguments: Sequence[Any]
         if arguments is None:
@@ -71,6 +93,22 @@ class AttributeAnnotation:
         required: bool,
         /,
     ) -> Self:
+        """
+        Update the required flag for this annotation.
+
+        The resulting required flag is the logical AND of the current
+        flag and the provided value.
+
+        Parameters
+        ----------
+        required : bool
+            New required flag value to combine with the existing one
+
+        Returns
+        -------
+        Self
+            This annotation with the updated required flag
+        """
         object.__setattr__(
             self,
             "required",
@@ -80,6 +118,17 @@ class AttributeAnnotation:
         return self
 
     def __str__(self) -> str:
+        """
+        Convert this annotation to a string representation.
+
+        Returns a readable string representation of the type, including
+        its origin type and any type arguments.
+
+        Returns
+        -------
+        str
+            String representation of this annotation
+        """
         if alias := self.extra.get("TYPE_ALIAS"):
             return alias
 
@@ -103,6 +152,29 @@ def attribute_annotations(
     /,
     type_parameters: Mapping[str, Any],
 ) -> Mapping[str, AttributeAnnotation]:
+    """
+    Extract and process type annotations from a class.
+
+    This function analyzes a class's type hints and converts them to AttributeAnnotation
+    objects, which provide rich type information used by the State system for validation
+    and other type-related operations.
+
+    Parameters
+    ----------
+    cls : type[Any]
+        The class to extract annotations from
+    type_parameters : Mapping[str, Any]
+        Type parameters to substitute in generic type annotations
+
+    Returns
+    -------
+    Mapping[str, AttributeAnnotation]
+        A mapping of attribute names to their processed type annotations
+
+    Notes
+    -----
+    Private attributes (prefixed with underscore) and ClassVars are ignored.
+    """
     self_annotation = AttributeAnnotation(
         origin=cls,
         # ignore arguments here, State (and draive.DataModel) will have them resolved at this stage
@@ -573,6 +645,38 @@ def resolve_attribute_annotation(  # noqa: C901, PLR0911, PLR0912
     self_annotation: AttributeAnnotation | None,
     recursion_guard: MutableMapping[str, AttributeAnnotation],
 ) -> AttributeAnnotation:
+    """
+    Resolve a Python type annotation into an AttributeAnnotation object.
+
+    This function analyzes any Python type annotation and converts it into
+    an AttributeAnnotation that captures its structure, including handling
+    for special types like unions, optionals, literals, generics, etc.
+
+    Parameters
+    ----------
+    annotation : Any
+        The type annotation to resolve
+    module : str
+        The module where the annotation is defined (for resolving ForwardRefs)
+    type_parameters : Mapping[str, Any]
+        Type parameters to substitute in generic type annotations
+    self_annotation : AttributeAnnotation | None
+        The annotation for Self references, if available
+    recursion_guard : MutableMapping[str, AttributeAnnotation]
+        Cache to prevent infinite recursion for recursive types
+
+    Returns
+    -------
+    AttributeAnnotation
+        A resolved AttributeAnnotation representing the input annotation
+
+    Raises
+    ------
+    RuntimeError
+        If a Self annotation is used but self_annotation is not provided
+    TypeError
+        If the annotation is of an unsupported type
+    """
     match get_origin(annotation) or annotation:
         case types.NoneType | None:
             return _resolve_none(